Fherosott Dynamics 2623 
Business Central 
API Reference | 


2nd Edition 


Enabling a better understanding of the 
Business Central API 


Foreword by Kennie Nybo Pontoppidan, 
Principal Program Manager, Microsoft 


9 


Jeremy Vyska, Mark Rembisz, Se. 


and Arend-Jan Kauffmann Spare Brained Ideas Q 


JIS 


Business Central API Reference 


Copyright ©2024 Spare Brained Ideas AB 


All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in 
any form without prior written permission from the author, except in the case of brief quotations embedded in 
critical articles or reviews. 


Every effort has been made to ensure the accuracy of the information, guidance, and steps presented in this 
book. However, this book is sold without warranty of results, express or implied. The authors cannot be held liable 
for any damages caused or alleged to have been caused directly or indirectly. 


First Edition Published: 2023-01-31 
Second Edition Published: 2024-09-29 


sparebrained.com 


FOREWORD 


APIs are the secret sauce for any integration to and from Dynamics 365 Business 
Central environments. You need to call an API if you use services such as Power BI, 
Power Automate or Flow, and if you set up barcode scanners, and use web shops, or 
shipping services. So, APIs should make much sense for any functional consultant 
working with Business Central because modern ERP systems today are seldom used as- 
is but is part of a richer ecosystem of external systems/services. 


Now, for the typical AL developer, the development and consumption of APIs are 
likely not something everyone regularly does. In this book, Jeremy, Mark and AJ try to 
bridge the gap between the consumer need for APIs and the developers. You will learn 
about the basics of web services and the APIs that are available out-of-the-box in 
Business Central. 


But you will also be introduced to best practices in API development, 
troubleshooting, and performance, skills that are crucial if you are to make APIs work 
in real life. 


This book should be in the local library for any serious Business Central partner 
practice out there. | truly hope that it will be used for developing these crucial skill for 
AL developers out there who want to help their customers take their ERP into the 
modern world. 


- Kennie Nybo Pontoppidan 
Principal Program Manager, Microsoft 


PREFACE 


This book is meant to be an introduction and a reference guide to accompany and 
supplement the official documentation from Microsoft. 


The Microsoft Dynamics 365 Business Central system is a very large and complex system, 
of which a small subset of functionality is available via the built-in API. 


WHO SHOULD READ THIS BOOK? 


This book is meant for two main audiences: 
Business Central Users and Advocates 


If you are a user, consultant, or developer working with Business Central, this book is 
hopefully useful to you as a guide to what parts of the system are accessible via API. Ideally, it 
will also make it easier to understand what each part of the API maps to the inside of Business 
Central. 


Non-Business Central Developers 


If you are a developer or organization that has been tasked with integrating with or 
building against the Business Central API, this book will help you understand what the options 
are in a single, unified place. It will also help you communicate more effectively with Business 
Central users about what you are creating. 


How TO READ THIS BOOK 


It is strongly recommended that you have a test company or a Sandbox copy of a 
company to follow along with as you read. For many of the examples shown in this book, we 
will also refer to looking at a CRONUS company - this is a demonstration and training company 
that Microsoft includes with the system. Typically, this is made to have data and language 
relevant to your local regulations and language. Our examples rely on the base CRONUS US 
data set. 


Part 1 is an introductory text to the system and understanding of core concepts. 


Parts 2-7 are broken down by which API Endpoint. In each Chapter of these Parts, you will 
find: 


e Which ACTIONs are supported. 
e Information about how the API fields map to the Business Central records/pages 
e Example URIs and responses 
e Avery limited guide to how to do each CRUD operation in BC for the given record, 
as relevant: 
o Create - making a new record. 
o Update - is anything you need to know about modifying an existing 
record. 
o Delete - deleting a record. 


Part 8 covers additional topics that are useful to know, including some critical 
understanding of how the API works and how to ensure you are tuning for performance. 


Part 9 contains additional resources that will help. 


And lastly, Part 10 is a quick reference table to easily find the endpoint information. 
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PART 1: Basic API CALLS 


In this Part, we will cover some of the core concepts you need to know about the different 
HTTP methods used in Business Central. A quick introduction using examples will show key 
points for each method. 


We will then summarize all the different endpoints as a list to provide an overview. 
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Chapter 1: Introduction 


WHAT IS THE BUSINESS CENTRAL API? 


At heart, the Business Central API is an HTTP Listener with a complex routing system that 
allows you to call specific endpoints to interact with a single piece of data or a set of data 
entries. The listener obeys the REST constraints, so it is a RESTful API. Business Central 
specifically allows the use of these HTTP Methods: 


e GET - to retrieve data. 
e POST - to create data. 
e PATCH - to update data. 
e DELETE - to delete data. 


Not all endpoints support all four methods, but these are the full range of options. 


KEY TERMS 


One area that often needs clarification for people new to the Business Central API is that 
the API is implemented as a part of the Web Services in Business Central, and it lives under the 
OData framework in Business Central. This means that the API is interacted with by using REST 
communication. Still, many of the rules and functionalities of OData also apply. This is because 
OData is built on top of the RESTful standard. 


This can make it difficult to follow for non-technical or new to API development people. 
You will hear people discuss the BC API and use all these following terms. 


API 


An API, an acronym for Application Programming Interface, generically describes how 
software components interact. APIs can be found everywhere, in operating systems, 
programming languages, etc. In terms of Business Central, APIs are mostly referred to as the 
set of endpoints that are exposed by Business Central to interact with data based on the OData 
v4 protocol. 
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WEB SERVICES 


Web Services are APIs accessible over a network (mostly over the internet, referred to as 
"the web"). Web Services and APIs are similar but not identical. API is an interface that exposes 
data or functions of an application, whereas web services are one type of API with stricter 
requirements. These requirements include communicating over a network, using a specific 
protocol like REST, etc. For Business Central, web services it the "umbrella" area for the HTTP 
listeners, including the SOAP interface and the OData v3 and v4 interfaces. 


REST 


It stands for REpresentational State Transfer, which is a resource-based architectural style. 
Resource-based means that data and functionalities are considered resources. REST has its 
guiding principles and constraints, which you can read more about here: https://restfulapi.net/ 


ODATA 


OData is a web-based protocol that defines a set of best practices for building and 
consuming RESTful web services. OData is a way to create RESTful web services; thus, an 
implementation of REST. It defines the data model used to transfer data in response to a REST 
request, including the HTTP message format, how to query the API and more. 


Although OData should follow REST principles, this requirement can be relaxed if there is 
a good reason. In addition, OData specifies that data should be transferred in XML Atom or 
JSON format. 


ENDPOINTS 
The URI that ties to a specific resource. 


In our Business Central world, for example, there is an endpoint for the Customer 
resource, which will always be available at a specific URI. Endpoints are implemented using 
Page or Query objects of type API and support namespace control and versioning. 


There are platform/technical endpoints for additional functionalities like batch calls and 
webhooks. 


CLOUD/SAAS vs. ON-PREMISES 


For Cloud (also called SaaS) users of Business Central, the API Web Services are 
automatically enabled. 


For On-Premises, this must be enabled in the Business Central server configuration. In the 
Business Central Administration tool, you must enable OData and the API services. It is strongly 
recommended to evaluate the ports, but this book will assume that you use the standard port 
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number 7048. You should also enable SSL for these systems, but those steps are beyond the 
scope of this book. 


The exact details of the endpoints should be checked on the Microsoft Docs site. For 
example, the API v2.0 documentation site has a page about the available endpoints here: 


https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api- 
reference/v2.0/endpoints-apis-for-dynamics 


For example, for our API v2.0 Cloud scenario, we have a URI: 


https://api.businesscentral.dynamics.com/v2.0/Sandbox/api/v2.0/companies 


For a single-tenant On-Premises installation, the URI is much simpler. In this case, we have 
an On-Premises server named bcserver. The same endpoint would be: 


http://bcserver:7048/bc/api/v2.0 


You will also need to resolve Authentication, to which an introduction is in Part 8: 
Chapter 87: Authentication (page 477). 


A note about the link examples in this reference book. In the urls, we have used a placeholder 
similar to Postman variables: 


{{tenantID}} - The guid id of your SaaS (cloud) environment. 
{{companyID}} - the guid id of the company that you are accessing. 
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Chapter 2: Reading / GET 


The GET method is the simplest on the surface — it is how you read data from the API. 
What is returned is either a collection or a single entity. 


BASIC USAGE — COLLECTION AND ENTITY 


From our earlier example, using our On-Premises instance, when we call the companies 
endpoint, we get a JSON Response as follows: 


{ 


"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/ 
Smetadata#companies", 
"value": [ 
{ 
UGG company LDI pW. 
"systemVersion": "24.1.18927.19498", 
"timestamp": 45290, 
"name": "CRONUS International Ltd.", 
"displayName": "", 


"businessProfileId": "", 


"systemCreatedAt": "2024-05-14T10:34:20.6832", 
"systemCreatedBy": "00000000-0000-0000-0000-000000000001", 
"systemModifiedAt": "2024-05-14T10:34:20.6832", 
"systemModifiedBy": "00000000-0000-0000-0000-000000000001" 


You will see we have two top-level parts: 


e Qodata.context - this is the way to get all the metadata for this URI, which can 
show you a lot of great information (see below) and actions. 
e Value -a JSON array of the result objects. 


If we were to use the OData method to request a single entity, the URI would look as 
follows: 


https://api.businesscentral.dynamics.com/v2.0/companies ({ {companyID} } 
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You will notice the companies node for which we are providing the id. This tells the 
Business Central OData engine that we want a specific record. In REST, this is referred to as a 
resource. Business Central will return a single resource entity in JSON format., as follows: 


{ 


"Qodata.context": "http://bcserver:7048/bc/api/v2.0/$metadatafcompanies/Senti 
ty", 

Viste: Comp any DD e 

"systemVersion": "24.1.18927.19498", 

"timestamp": 45290, 

uname 1 MERONUS international LEd un 

taisplayNamens uim 

InsusdmessEBcotuddeTdqu uu 

"systemCreatedAt": "2024-05-14T10:34:20.6832", 


"systemCreatedBy": "00000000-0000-0000-0000-000000000001", 
"systemModifiedAt": "2024-05-14T10:34:20.6832", 
"systemModifiedBy": "00000000-0000-0000-0000-000000000001" 


UNDERSTANDING ID VALUES 


One area that can cause some confusion for people working with Business Central APIs is 
Primary Keys and IDs. 


All tables have a primary keycomprised of one or more fields. Commonly, these fields are 
either alphanumeric values or integer values for many core parts of the system. Additionally, 
Business Central has, in the past few versions, added a new Unique record ID field called 
Systemld (inside Business Central), which is a GUID type (a 32-digit alphanumeric). The APIs 
usually expose the Systemld field as id. The ID system was introduced to provide a 10096 
immutable unique identifier. 


In Business Central, the user may rename a record, but you would want your API 
connections to retain the connection. For example, if a Customer is renamed from CUST0010 
to GLOBALCOM, you would not want a Webshop to be unable to locate the Customer, or your 
CRM system to think you need all those contact records to be recreated. 


It is this immutable Systemld/id field that is typically used in the URI to identify a single 
record (for BC Developers, this is based on the ODataKeyFields property of an API page, not 
built-in by default — so you must build custom API endpoints thoughtfully!) to ensure you are 
getting the exact correct record every time. 


@ Note for Business Central Developers: The id used by the OData 


engine is tied to the AL Property called ODataKeyFields, which 
is often the Systemld, but can be other values in a Custom API, 
such as a "Document No." or multi-field combinations. 
Systemld is usually used because it is now built into the 
Business Central Engine and is unchangeable, even if the Record 
is renamed. 
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This also comes up in Business Central with fields that are related - those that hold values 
to other records. For example, you can access/change the Customer's default Currency Code 
on the Customer Card in Business Central. This will show up in the API in two fields: 


"currencyId": "05c92172-a1a6-ec11-8370-8cc96a41ed4e", 
"currencyCode": "EUR", 


On the Customer Card, you will see the EUR value, but if you want to work with the related 
Currency from the Currencies endpoint, you will need to use the currencyId GUID. 


itis important to consider whether those IDs should be provided 
and how you need to handle the validations. This can also have 
a large effect on the Expand functionality. 


o Note for Business Central Developers: Working with custom APIs, 
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OPTIONS AND ENUMS 


Option and Enum fields are displayed in the Ul as a drop-down menu of strings. In APIs, 
these fields are also exposed as strings. However, there is one oddity: spaces are represented 
as "_x0020_". Below is a JSON representing some fields of a customer record: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/customers/Sentity", 
"@odata.etag": "W/N"JzESOzE5MjYONjEzMjYONTO2NTYOMDAxOzAwOyc-V"", 
"id": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 
"displayName": "Adatum Corporation", 
Ubikockedus a 0020m 


The strange value for the field blocked is, in fact, the Unicode-encoded representation of 
a space. All option and enum fields are exposed as OData enumeration fields that represent a 
series of allowed values. The OData schema of all fields contains an EnumType definition for 
all option and enum fields. It appears as follows: 


<EnumType Name="customerBlocked"> 
<Member Name="_x0020_" Value="0" /> 
<Member Name="Ship" Value="1" /> 
<Member Name="Invoice" Value="2" /> 
<Member Name="A11" Value="3" /> 
</EnumType> 


The OData specification requires the value of the name to start with a letter or underscore. 
A space would not comply with that rule. So instead, the Unicode-encoded value is used to 
represent a space. 


Note: There is a great deep dive on schema and OData handling at: 
https://www.kauffmann.nl/2024/08/22/custom-apis-and- 
schemaversion-2-0/ 


When sending data to a Business Central, it is still possible to use a space instead of the 
Unicode value. The Business Central OData stack will translate it into the correct enum value. 
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EXPANDING / NAVIGATION 


One area that confuses many people working with the Business Central API is the concept 
of “Navigation” and expanding. 


For example, if we take this excerpt from the v2.0 Item API Documentation: 


Navigation 


Navigation Return Type Description 

itemCategory itemCategory Gets the itemcategory of the item. 
unitOfMeasure unitOfMeasure Gets the unitofmeasure of the item. 
picture picture Gets the picture of the item. 
defaultDimensions defaultDimensions Gets the defaultdimensions of the item. 


itemVariants itemVariants Gets the itemvariants of the item. 


Properties 


Property Type Description 


id GUID The unique ID of the item. Non-editable. 


number string Specifies the number of the item. 


displayName string Specifies the item's name. This name will appear on all sales documents 
for the item. 


If we look at Item Entity: 


{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/$metadata#tco 
mpanies ({ {companyID}}/items/Sentity", 

"Qodata.etag": "W/N"JzQ0O3hnVWcrYnFNSDlxdFhzczF6NTV3ZnJpdlQzblZBaTBWdVMAdX12N 
VAzL1k9MTswMDsn\"", 

"id": "8401bb9a-1154-ec11-836a-bb3a0749995d", 

Whumoper i 18/9657 

"displayName": "ATHENS Desk", 

teo etu UA ment o£yl 

"itemCategoryId": "8205bb9a-1154-ec11-836a-bb3a0749995d", 

"itemCategoryCode": "TABLE", 

"blocked": false, 

Wigneakja s UT 

"inventory": 4, 

"unttbricew: 649.4, 

"priceIncludesTax": false, 

Ubyaabielerosna MB. SOG tei, 

"taxGroupId": "00000000-0000-0000-0000-000000000000", 


MuaxGroupecOcdenl INT 

"baseUnitOfMeasureId": "03025bb9a-1154-ec11-836a-bb3a0749995d", 
"baseUnitOfMeasureCode": "PCS", 

"generalProductPostingGroupId": "8003bb9a-1154-ec11-836a-bb3a0749995d", 
"generalProductPostingGroupCode": "RETAIL", 
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"inventoryPostingGroupId": "ef0lbb9a-1154-ecl11-836a-bb3a0749995d", 
"inventoryPostingGroupCode": "RESALE", 
"lastModifiedDateTime": "2023-12-03T708:20:05.9772" 


While we see the fields mentioned in Properties, we do not see the Navigation elements 
in the dataset. 


This is for efficiency reasons - the related records are additional data fetches. As such, 
you need to explicitly ask for expanding the Navigation elements. 


For our On-Premises example URI, it gets this extra text (bolded) at the end: 


https://api.businesscentral.dynamics.com/v2.0/companies ({ {companyID}}/items (8401b 
b9a-1154-ec11-836a-bb3a0749995d) / ?$expand-itemCategory 


By supplying the $expand parameter, we can tell the Web Services that we want the 
related data from that Navigation element. This expands the Item object to look as follows: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}}/items/Sentity", 
"Qodata.etag": "W/\"JzQ003hnVWerYnFNSD1xdFhzczF6NTV3ZnJpd1Q0zb1ZBaTBWdVM4dX12N 
VAzZL1k9MTswMDsn\"", 
"id": "8401bb9a-1154-ec11-836a-bb3a0749995dà", 
Vnurmbemr: S9 SM 
"displayName": "ATHENS Desk", 
Eel 
WlastModifiedDateTime™: “2023-12-03703:20;05. 9772", 
"itemCategory": { 
"Qodata.etag": "W/N"JzQ0O04xV1gxRUkyUy9kMkNGZktNNXR2WnBaMmZLbmQvYUMOMIVqe 
jdpUlEvYmM9MTswMDsnN"", 
mac ao5I»bOa Usi» eet 956a Iia0gd999 scr, 


teodet NT NBISEM 
"displayName": "Assorted Tables", 
"lastModifiedDateTime": "2023-12-03T708:19:01.7272" 


You can see that we get an extra nested object for itemCategory. 


It is possible to expand multiple entities (comma separated), and the Navigation can also 
be collections, so if we expand on itemCategory,itemVariants, we will see: 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}}/items/Sentity", 
"Qodata.etag": "W/\"JzQ0O03hnVWcrYnFNSD1xdFhzczF6NTV3ZnJpd1Qzb1ZBaTBWdVM4dX12N 
VAzL1k9MTswMDsn\"", 
"id": "8401bb9a-1154-ec11-836a-bb3a0749995d", 
number MENOS 
om 
WlastModifiedDateTime™:; U2Z023-12—-0370/3 22005. 9772, 
"itemCategory": { 
"Qodata.etag": "W/N"JzQ0O04xV1gxRUkyUy9kMkNGZktNNXR2WnBaMmZLbmQvYUMOMIVqe 
jdpUlEvYmM9MTswMDsnN"", 
Wiles WSy?IOSysiofekeic TL 054 exe Tl SI Gevtolo) sad) 7/416) e) Orel. 
Mecodc ABE 
"displayName": "Assorted Tables", 
"lastModifiedDateTime": "2023-12-03708:19:01.7272" 


h ) 
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"itemVariants": [] 


Note that a single object, like itemCategory, is represented with a single name, while a 
collection, like itemVariants, is represented with a plural name. 


It is also possible to expand on multiple levels. For example, salesOrders can be 
expanded with properties like paymentTerm and salesOrderLines. While in its turn, a 
salesOrderLine can be expanded with account or item. As we have seen above, the item 
entity can be expanded with itemCategory. This can all be combined in a single URI (leaving 
out the base URI for brevity): 


/salesOrders (7930b2a0-1154-ec11-836a-bb3a0749995d) / 
?Sexpand=paymentTerm, salesOrderLines ( 
Sexpand=account, item ($expand=itemCategory) ) 


Note: be careful with expanding extra properties. When used 
on a collection instead of a single record, they can seriously impact 
the performance of the API request. See Part 8: Chapter 89: 
Performance (page 511). 


SELECTING FIELDS 


One of the OData operations you can also use when requesting results from the Business 
Central API is the $select query option. This allows you to supply a subset of the fields 
available if you only need partial information. 


For example, if you just need a list of Customer Names and Numbers, but none of the 
additional information available from the Customer endpoint, you can add 
$select=number ,displayName to the end of the Customer GET call: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /customers?$select=number ,displayName 


This will return the Customers list with only the eTag the fields explictly requested: 


{ 
"Qodata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({{companyID}})/customers", 
"value": [ 
{ 
"@odata.etag": "W/\"JzIwOzEwNDc2MTcOMzc1MzIzODgSMTkwMTswMDsn\"", 
"number": "10000", 
"displayName": "Adatum Corporation" 


"@odata.etag": "W/N"JzE5OzMxNjY5MTExNjk5OTkwOTQ2O0DExOzAwOyc-N"", 
"number"; "20000", 
"displayName": "Trey Research" 
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"Qodata.etag": "W/N"JzE5OzMAMTIzNzYyNjIzNDk5MTAzNzIxOzAwOyc-N"", 
number wa 30/00/07 
"displayName": "School of Fine Art" 


"Qodata.etag": "W/\"JzIwOzE20DA40Tc1MzQONTELOTMxNDkK5MTswMDsn\"", 
"number": "40000", 
"displayName": "Alpine Ski House" 


Be aware that $select is one of your best tools for massive performance gains, 
particularly when you combine calls using $expand. For more information, see Part 8: Chapter 
89: Performance (page 511). 


CHANGING RESULTS ORDER 


If you wish to receive the results of an API call pre-sorted, this is done using the OData 
query option called $orderby. For example, we could request that Customers be sorted by 
the largest Balance Due first using ?$orderby-balanceDue desc: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies((companyID)])/customers?$orderby-balanceDue desc 


LIMIT RESULTS 


When there is a scenario where you only require a partial list, such as the most recent 
sales order for a customer, you can combine the filtering, select, and sorting along with the 
$top OData query option to get a subset of the results available: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID))/APIBook/api/v2.0/compa 
nies((companyID)]))/salesOrders?S$filter-customerId eq 6c15971e-df3a-edll-bbae- 
6045bd8e554a&$orderby-orderDate desc&$top-l&$select-id,number 


This will limit the number of results to the quantity you specify, as shown in the example 
above which will return only 1 partial record. 


{ 


"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/APIBook/api/ 
v2.0/Smetadata#companies ({{companyID}})/salesOrders", 
"value": [ 


{ 


"Qodata.etag": "W/\"JzE50zY20Dg30Dc1NDMOMTkwOTE1MzAxOzAwOyc=\"", 
"id": "0a251e29-df3a-edl1-bbae-6045bd8e554a", 
“number i US- ORIIIOOAN 
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For more information, including important things to know about use of $top, see Part 8: 
Chapter 89: Performance (page 511). 


COUNTS 


There are times when all you need is a count of records that meet a set of criteria, and 
the $count query option will indicate that you want a count only. This will return a single 
integer value, not even a JSON. 


Unlike other query options, this is part of the path. So, it goes before the ?. 


For example, if we want a count of all orders open for a specific Customer, we can GET: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/salesOrders/S$count?Sfilter=customerId eq 6c15971le-df3a-ed11- 
bbae-6045bd8e554a 


This returns a raw integer value: 


SKIPPING RECORDS 


It is common to need to fetch information in batches, which requires being able to skip a 
number of records previously requested. This is accomplished via the $skip query option. For 
our earlier example where we requested the most recent order for a customer, we now may 
wish to get all the other orders: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID))/APIBook/api/v2.0/compa 
nies ({companyID}})/salesOrders?S$filter=customerId eq 6c15971e-df3a-edll-bbae- 
6045bd8e554a&S$orderby-orderDate desc&$skip-1 


This will return the list of orders open, skipping the most recent (due to the $orderby 
on the orderDate). 


For more information, including important things to know about use of $skip, see Part 
8: Chapter 89: Performance (page 511). 


FILTERING 


There are also many ways to apply filters against the API using the $£ilter query option. 
However, that deserves its own Chapter, which is found in Part 8: Chapter 90: Filtering Syntax 
(page 514). 
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Chapter 3: Insert / POST 


Creating a record in the BC API is relatively simple since so many records in Business 
Central are designed and configured to automatically be assigned a Primary Key (such as Items 
getting an item number). 


For example, when creating an Item, we do a POST command to the items endpoint. In 
the Request, we supply a body of JSON data as follows: 


{ 
"displayName" : "The Best Lil' API Book" 


} 


Everything else besides the displayName (the Description field inside Business Central) 
will default if possible. We get a SUCCESS notice when we make the call, so it returns the 
resulting entity: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}}/items/Sentity", 

"Qodata.etag": "W/N"JzQ0OzMvVEAvYkxLMTFuRmROQ3hSQWCUTUFZNTAANSs2O0TgvQ2J)UmTS9ZY 
mdBVHc9MTswMDsnN"", 

"id": "62eaa76b-3d54-ec11-836a-bb3a0749995dà", 

Umum ete HON 

"displayName": "The Best Lil' API Book", 

Wienges: Time mts oval 

"itemCategoryId": "00000000-0000-0000-0000-000000000000", 

"itemCategoryCode": "", 

"blocked": false, 

eini " n 

“inventory: 0p 

Un EPELEN Tn 

"priceIncludesTax": false, 

vuni Costs Ol, 

"taxGroupId": "00000000-0000-0000-0000-000000000000", 


WeaxGroupCodems Ww" 

"baseUnitOfMeasureId": "0302bb9a-1154-ec11-836a-bb3a0749995d", 
"baseUnitOfMeasureCode": "PCS", 

"generalProductPostingGroupId": "8003bb9a-1154-ec11-836a-bb3a0749995d", 
"generalProductPostingGroupCode": "RETAIL", 

"inventoryPostingGroupId": "ef01bb9a-1154-ec11-836a-bb3a0749995dg", 
"inventoryPostingGroupCode": "RESALE", 


Ins sMociisiareciaiegmumelv-: 2/025: 9. 065] 9:95 2/ 59/5 8]]E9 71M 


It is even possible to use the Navigation properties to do something called "deep insert", 
where you call an endpoint, create the ‘header’ record and multiple lines, such as: 
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DnwouceDauest- 2x qu — 2) (ier 
"dueDate": "2023-12-20", 
ueuscomer TI WE O OW - 
"salesInvoiceLines" : [ 


VapEGmelg. WAL eyes 
Wreiiicioncaey/ M S JE 


Woneamurel¥s WS 
JewesibaLipy e (S 


This is often a smart way to create a document (such as an order or invoice) to ensure 
that if one part fails, the rest of the transaction rolls back, and you are not left with a partially 
created document. 
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Chapter 4: Delete / DELETE 


The DELETE method is simple enough. You must use a URI that specifies a single entity 
and use the DELETE method. For example, if we created a new Item that has a Systemld of: 


04ab149c-4054-ec11-836a-bb3a0749995d 


We would then call DELETE to the URI: 


https://api.businesscentral.dynamics.com/v2.0/companies ({ {companyID}}/items (04ab1 
49c-4054-ec11-836a-bb3a0749995d) 


No body is sent on success, just a Status: 204 No Content. 
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Chapter 5: Update / PATCH 


Business Central uses a technology under the hood that follows the guiding principles of 
optimistic concurrency. If you are a user of Business Central, you have probably seen either the 
older “Another user has modified the record” message or the latest “Sorry, we just updated 
this page” message. 


For a concrete example, let us take a Customer entity in Business Central and have two 
people try to change it simultaneously. Sophie in Sales and Gabriel in Accounting both open 
the Customer Card. Sophie changes the Phone Number. Gabriel changes the Credit Limit. Both 
change the Contact Name. Now what happens? 


The way Business Central handles this is by keeping track of what ‘version’ is the latest. 
When we ask Business Central to save changes (which the web UI does for us), it checks to 
make sure the version of the entity we are looking at is the same version as the ‘latest’ changes. 


If there is a mismatch, as there would be for Gabriel, Business Central will ‘reject’ Gabriel's 
change and tell him to start over from the latest version. 


In the API version of modifying a record, the PATCH method, we must supply a token that 
maps to precisely which version of the record, so it can validate we are safely not overwriting 
changes. This is done via the eTag system. You might have spotted it in the earlier results. 
During our POST call, we got the result: 


{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}}/items/Sentity", 

"Qodata.etag": "W/N"JzQ0OzMvVEAvYkxLMTFuRmROQ3hSQWCUTUFZNTAANSs2OTgvQ2J)UmTS9ZY 
mdBVHc9MTswMDsnN"", 

"id": "62eaa76b-3d54-ec11-836a-bb3a0749995d", 

"number": "1000", 

"displayName": "The Best Lil' API Book", 
Eo aall 


That @odata . etag is the version token for the record. When we call a PATCH command 
to the system, we must either supply the exact right etag or tell Business Central that we want 
to override any version checking. 


To override the version checking in your headers, supply the extra header: 


Me Maite hac 
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To use the eTag value, be aware that it is encoded in the result set (based on the Record 
ID and timestamp, for the curious). In our example above, if we want to PATCH the Item we 
received, we need to supply the extra Header with the request: 


Te Mairen 
W/"JzQ0OzZMvVVE4vYkxLMTFURMROQ3hSQWtŁUTUFZNTA4NSs2OTgvQ2JmTS9ľ9ZYmABVHCc9MTswMDsn" 


In Postman, it is added in the Headers section: 


Params Authorization @ Headers (11) Body e Pre-request Script Tests Settings 


Headers 10 hidden 
KEY VALUE 


If-Match W/'JzlwOzExMjQ2MDYyOTYOOTg3MzExMjUOMTswMDsn" 


The value in the @odata.etag from Business Central contains double quotes within it. 
As a result, they are escaped (preceding backslashes). You need to take the value from: 


W/N"JzIwOzExMjQ2MDYyOTYOOTg3MzExMjUOMTswMDsn'N" 


And change it to: 


W/"JzIWOzExMjQ2MDYyOTYOOTg3MzExMj UOMTswMDsn" 


The Request Body JSON only needs to include the fields that you wish to update, the 
same as POST. And you will receive back a new version of the record, including the new eTag 
of the new version. For the Book item we created before if we update the unitPrice to 30: 


mae Paste e mS 


We will get the updated record: 


{ 


"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/$metadata#co 
mpanies ({ {companyID}}/items/Sentity", 

"Qodata.etag": "W/\"JzQ0O0YrUTd6QnhxMU5uaGdOYUMrem0wN1UrTmk4L3FwTEhuUU11bFVIO 
nM4Q1E9MTswMDsn\"", 

"id": "62eaa76b-3d54-ec11-836a-bb3a0749995d", 

inm» esto OIN 

"displayName": "The Best Lil' API Book", 

IU teypet mt mrent or yl 

"itemCategoryId": "00000000-0000-0000-0000-000000000000", 

"itemCategoryCode": "", 

"blocked": false, 

Jienpsboq s mae 

Maine mit ere yi Ol, 

Mbit S10), 

"priceIncludesTax": false, 

Withnabieosiel B. (0), 
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"taxGroupId": "00000000-0000-0000-0000-000000000000", 

MeaxGroup Coder: 

"baseUnitOfMeasureId": "0302bb9a-1154-ec11-836a-bb3a0749995d", 
"baseUnitOfMeasureCode": "PCS", 

"generalProductPostingGroupId": "8003bb9a-1154-ec11-836a-bb3a0749995d", 


"generalProductPostingGroupCode": "RETAIL", 
"inventoryPostingGroupId": "ef01bb9a-1154-ec11-836a-bb3a0749995d", 
"inventoryPostingGroupCode": "RESALE", 


"lastModifiedDateTime": ”2023-12-03T15:18:41.567Z" 
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Chapter 6: Calling Bound Actions 


There are times when you may wish to trigger the execution of an Action inside Business 
Central. For example, you may need to trigger Posting a Sales Invoice or Receive and Invoice a 
Purchase Order. 


This is as simple as calling a POST method against the right single Entity URI (you cannot 
do this for a collection), with a trailing / and the action. If we look at the 
api/v2.0/$metadata, way down in the specification, we will find there is an Action: 


<Action Name="post" IsBound-"true"» 
«Parameter Name="bindingParameter" Type="Microsoft.NAV.salesInvoice" /» 
</Action> 


This means that on the salesInvoice endpoint, we can call this action with a prefix. The 
method is POST (the name is a coincidence - all actions are POST method calls). In this case, it 
would look as follows: 


https://api.businesscentral.dynamics.com/v2.0/companies ({ {companyID}}/salesInvoic 
es (a6£eldel-4d54-ec11-836a-bb3a0749995d) /Microsoft.NAV.post 


You will note that the URI needs to call a single instance of a record, so it is structured 
like / (entity) ({id}) /Microsoft.NAV. {actionName}. If there are any error messages 
that would be normally displayed to the user, they will come in the Response as follows: 


{ 


"error": 4 
cose Mri eaturengiralltegBxeepbems 
"message": "Please add at least one line item to the invoice.  Correlatio 


nid: fdd45e81-7b54-496b-bcb3-60aa8b599470." 
} 
} 


If the action is completed, like the DELETE method, you will only get a Status 204 No 
Content response. 


There are also Unbound actions, but they are beyond the scope of this edition of the 
book. 
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Chapter 7: The API v2.0 List 


Endpoints Alphabetically 
accounts 


Business Central 
Page / Report 
Chart of Accounts 


accountingPeriods 


Accounting Periods 


agedAccountsPayables 


Report: Aged Accounts 
Payable 


agedAccountsReceivables 


Report: Aged Accounts 
Receivables 


applyVendorEntries 


Payment Journal -> 
Apply Entries 


attachments 


Incoming Documents 


balanceSheets 


Financial Reports 


bankAccounts 


Bank Accounts 


cashFlowStatements 


Financial Reports 


companies 


Companies 


companylInformation 


Company Information 


contacts 


Contacts 


contactsInformation 


Contact Card -> 
Business Relations 


countriesRegions 


Countries/Regions 


currencies 


Currencies 


currencyExchangeRate 


Currency Exchange Rate 


customers 


Customers 


customerContacts 


Contact 


customerFinancialDetails 


Customers 


customerPayments 


General Journal 


customerPaymentJournals 


General Journal Templates 
-> Batches 


customerReturnReasons 


Return Reasons 


customerSales 


Customer and Customer 
Ledger Entries 


«| «[&| &|&I&IK&I&I&|&| &I&I&I&I&I&IK&IS| «| «| IRIS 


defaultDimensions 


Default Dimensions 
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Endpoints Alphabetically 
dimensions 


Business Central 
Page / Report 
Dimensions 


dimensionSetLines 


Dimensions 


dimensionValues 


«[&« 


Dimension Values 


disputeStatus 


Dispute Status 


documentAttachments 


Document Attachments 


employees 


Employees 


fixedAssets 


Fixed Assets 


fixedAssetLocations 


FA Locations 


generalLedgerEntries 


G/L Entries 


generalLedgerSetup 


General Ledger Setup 


generalProductPostingGroups 


Gen. Prod. Posting Groups 


incomeStatements 


Financial Reports 


inventoryPostingGroups 


Inventory Posting Groups 


items 


Items 


itemCategories 


Item Categories 


itemLedgerEntries 


Item Ledger Entries 


itemVariants 


Item Card -» Variants 


journals 


General Journal Templates 
-» Batches 


journalLines 


General Journal 


locations 


Locations 


opportunities 


Opportunities 


paymentMethods 


Payment Methods 


paymentTerms 


«[&«[&«| SIS 


«[&[&«| SIS 


«[&[&«| SIS 


Payment Terms 


pdfDocument 


Varies by Filters 


pictures 


Varies by Filters 


projects 


Jobs 


purchaseCreditMemos 


KISISISISISISIRI KS] «IIIA 


SISTIS 


SIS IS 


Purchase Credit Memos or 
Posted Purchase Credit 
Memos 


purchaseCreditMemoLines 


Purchase Credit Memos or 
Posted Purchase Credit 
Memos 


purchaselnvoices 


Purchase Invoices or 
Posted Purchase Invoices 


purchaselnvoiceLines 


Purchase Invoices or 
Posted Purchase Invoices 


purchaseOrders 


Purchase Orders 


purchaseOrderLines 


Purchase Orders 


purchaseReceipts 


Posted Purchase Receipts 


purchaseReceiptLines 


Posted Purchase Receipts 


retainedEarningsStatements 


Financial Reports 


salesCreditMemos 


KISISIA ISIS] S « 


Sales Credit Memos or 
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Endpoints Alphabetically 


Business Central 
Page / Report 
Posted Sales Cred. Memos 


salesCreditMemoLines 


Sales Credit Memos or 
Posted Sales Cred. Memos 


salesInvoices 


Sales Invoices or 
Posted Sales Invoices 


salesInvoiceLines 


Sales Invoices or 
Posted Sales Invoices 


salesOrders 


Sales Orders 


salesOrdersLines 


Sales Orders 


salesQuotes 


Sales Quotes 


salesQuoteLines 


Sales Quotes 


salesShipments 


Posted Sales Shipments 


salesShipmentLines 


Posted Sales Shipments 


shipmentMethods 


Shipment Methods 


taxAreas 


VAT Bus. Posting Groups or 
Tax Areas 


taxGroups 


VAT Prod. Posting Groups or 
Tax Groups 


timeRegistrationEntries 


Time Sheets 


trialBalances 


Report: Trial Balance 


unitsOfMeasure 


Units of Measure 


vendors 


Vendors 


vendorPayments 


General Journal 


vendorPaymentJournals 


General Journal Templates 
-» Batches 


vendorPurchases 


«| &I&&««|&[«| «| SI&«I&I&I&I&IS| «S | «S 


Vendor and Vendor Ledger 
Entry 


* Unless otherwise noted above, the API v2 was added in 17.0, so the endpoints listed with no 
marking are valid as of 17.0 forward. 
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PART 2: FINANCIALS ENDPOINTS 


In this Part, we will cover the various Financials related endpoints in Business Central. 


This covers core Financial setup information, such as the General Ledger and Bank 
Accounts, along with reporting and journal transactions. 


PART 2: FINANCIALS ENDPOINTS PAGE 
CHAPTER 7: THE API v2.0 LisT 


Chapter 8: Accounts 


The Account endpoint here refers to the G/L Account (General Ledger Account, visible 
via the Chart of Accounts in Business Central). 


Primary Key 


No. The identifier of the G/L account. The field is 20 characters, and 
alphanumeric. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/accounts/Sentity", 

"Qodata.etag": "W/N"JzE5OzYAMDA5MTM5MDIwNDU3NZzUwMTgxOzAwOyc-N"", 

"id": "1c15971e-df3a-ed1l1-bbae-6045bd8e554a", 

"uumbez!: 9m 

"displayName": "BALANCE SHEET", 

"category": "Assets", 

"subCategory": "Assets", 

"blocked": false, 

"accountType": "Heading", 

"directPosting": false, 

"netChange": O0, 

"lastModifiedDateTime": "2022-09-23T01:29:40.7532" 


BUSINESS CENTRAL ENTITY: 
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G/L Account Card 


10000 - BALANCE SHEET 


Process Account 


General 


No. 

Name 
Income/Balance 
Account Category 
Account Subcategory 
Debit/Credit 

Account Type 


Totaling 


e 


Balance More options 


Show more 


10000| nunber | Balance 0.00 
BA displayNane | Reconciliation Account 

Balance Sheet Automatic Ext. Text 

Asl category Direct Posting J 
As| subCategory e Blocked @ ) 


Debit Last Date Modified 8/29/2022 


Hd accountType Omit Default Descr. i... e ) 


CRONUS USA, Inc. | Finance Cash Management Sales Purchasing i = 


Chart of A! nts: 


All v O Search -}New [li] Delete — EZ Edit List Process v Se Account v 


Income/Ba... 


BALANCE SHEET Balance Sheet 


ASSETS Balance Sheet 


Checking account Balance Sheet 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID)])/accounts 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({{companyID}}) /accounts (1c15971e-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (single): 
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"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/accounts/Sentity", 

"Qodata.etag": "W/\"JzE50zY 4MDA5MTM5MDIwNDU3NzUwMTgxOzAwOyc=\"", 

"id": "1c15971e-df3a-edl1-bbae-6045bd8e554a", 

rto e: S000 

"displayName": "BALANCE SHEET", 

Icalsedgonyl ASSES, 

"subCategory": "Assets", 

"blocked": false, 

"accountType": "Heading", 

"directPosting": false, 

"netChange": 0, 

wiaceModiatriedDarelimet se 022 O97 TOn 01987410). 7/5) pd 


CRUD Steps 


CREATING 


To create a new G/L Account in Business Central, locate the Chart of Accounts and click 
the New button in the action bar 


CRONUS International Ltd. Sales Purchasing 


Chart of Accounts: — All v Jo d-New [ij Delete — EZ Edit 


Name 
BALANCE SHEET 
ASSETS 


Fixed Assets 


Consult with your BC team about which number and other settings will be useful. The No. 
field is alphanumeric, so you can add accounts like ZZZ-TESTO1. 


UPDATING 


The safest and simplest method to trigger an Update of a G/L Account is to alter the 
Name field. 


DELETING 


G/L Accounts can be deleted but make sure that this should be an Account with no 
transactions associated with it. 
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Bound Actions 


No bound actions. 


Navigation 


e trialBalances (Page 88) 


History 


Field Added: excludeFromConsolidation 


Field Added: consolidationTranslationMethod, consolidationDebitAccount and 
consolidationCreditAccount 
netChange added 
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Chapter 9: Accounting Periods 


This endpoint allows access to the account periods page in Business Central. 


Primary Key 


Starting Date The Start Date of the period, Date fieldtype and normally the first day 
of the month. 


Field Map 


API JSON: 
{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies (9be7cal4-5cfl-eell-a200-6045bde9b95f)/accountingPeriods", 

"value": [ 


{ 


"Qodata.etag": "W/N"JzIwOzEwMjMOOTC2O0DEONDMwMDgA4OTOxMTswMDsnN"", 
"id": "A4bb12a32-5cfl-eell1-a200-6045bde9b95f", 

Misibatieing Datel a O24 — Oe Ona 

"name": "January d 

"newFiscalYear": true, 

"closed": true, 

"dateLocked": true, 

"lastModifiedDateTime": "2024-04-03T01:50:12.9172" 


"Qodata.etag": "W/N"JzIwOzExMjglODgxNzYA4MDg3NjY1NDMxMTswMDsnN"", 
"id": "4cb12a32-5cfl-ee11-a200-6045bde9b95f", 


BUSINESS CENTRAL ENTITY: 
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I 


p t 


fa Inventory Period 


Starting Date 1 


+New BEEditLlist [ij 


B5 Create Year... 


Uu | 01/01/2024 


01/02/2024 
01/03/2024 
01/04/2024 
01/05/2024 
01/06/2024 
01/07/2024 
01/08/2024 
01/09/2024 
01/10/2024 


Accounting Periods | Work Date: 22/01/2026 


Delete Home 


B& Close Year 


Name 
January 
February 
March 
April 

May 

June 

July 
August 
September 


October 


Reports 


v Saved 


More options 


New Fiscal 
Year 


Inventory 


Date Locked Period Closed 


B 


JIDIOIOIDIOID uo 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies({{companyID}})/ accountingPeriods/ 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies({{companyID}})/ accountingPeriods (71cb189f-ddll-ef11-9f85b-6045bde9cc61) 


Example GET Response (single): 


{ 


"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({ {companyID}}) /accountingPeriods/Sentity", 
"@odata.etag": "W/\"JzIwOzEyNTk3MTEWNTY zOTg3Mzg3MDgwMTswMDsn\"", 


Eee Wikio Che ddi er Li Suelo GOA SloclaciceGul Wr 
ostar ingpacew UP (0E 

"name": "January uU, 

"newFiscalYear": true, 

"Closed": true, 

"dateLocked": true, 


nyaseMocistaecdbatemimet-:u2024-— 095-4 10/7 99990/0 921 


CRUD Steps 
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CREATING 


Run the “Create Year...” report to generate a fiscal year. 


< Accounting Periods | Work Date: 22/01/2026 v/ Saved 


[ud] +New &EditList [fj Delete Home Reports More options 


fe Inventory Period ez Create Year... Bez Close Year 


New Fiscal Inventory 
Starting Date Name Year Closed Date Locked Period Closed 


01/01/2024 : January 
01/02/2024 February 
01/03/2024 March 
01/04/2024 April 
01/05/2024 May 
01/06/2024 June 
01/07/2024 July 
01/08/2024 August 
01/09/2024 September 
01/10/2024 October 
01/11/2024 November 
01/12/2024 December 
01/01/2025 January 
01/02/2025 February 


0 OA 


Boo0oooooo dl 


UPDATING 


Once created, modifications to the accounting periods are rarely done and therefore are 
not covered by this reference book. 


DELETING 


Deleting lines is disallowed if the line is Closed, Date Locked or if the Inventory Period is 
closed. 


Bound Actions 


No bound actions. 


No navigations. 


History 


| Version Changes 


23.0 Added. 
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Chapter 10: Balance Sheets 


Being a financial accounting system, Business Central has many ways to get different key 
reports out of the system. The Balance Sheets endpoint is one way to obtain the data that 
would underly one of the core financial reports. 


The Balance Sheet API pulls from the Financial Reporting system. The Financial Report 
used can be configured in the Reporting section of the General Ledger Setup: 


General Ledger Setup 


General Posting Tax Bank Journal Templates 


Reporting 


Financial Report for Balance Sheet M-BALANCE 


Financial Report for Income Stmt. M-INCOME 


Financial Report for Cash Flow Stmt. M-CASHFLOW 


Financial Report for Retained Earn. M-RETAIND 


The Financial Report For Balance Sheet controls the results. However, unlike the full 
Financial Report, only the Balance column will be returned, regardless of how many columns 
are defined. 
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system is known by Account Schedules in prior versions. 


eo Note: The Financial Reporting area of the Business Central 


Primary Key 


N/A This API is a query that does not directly expose a table, so there is no 
Business Central primary key. Each record in the results will be unique 
per Financial Report Line. 


Field Map 


API JSON: 


"Qodata.etag": "W/N"JzIwOzEAMTEOOTI2MTM3NTkONDI2MDA3MTswMDsnN"", 
"id": "519d3all-df3a-edl1-bbae-6045bd8e554a", 
"lineNumber": 30000, 


Vlsrodbew er Weersia! 
“balancen 76549 29 
"lineType": "detail", 
Umcdemnisatd oni 


"dateFilter": "2024-05-30" 


BUSINESS CENTRAL ENTITY: 


The easiest way to see the results of the Balance Sheet output is to open the Financial 
Report set to the Financial Report For Balance Sheet from the General Ledger Setup. 


In the example above, the example row is the 3 line (30000 divided by 10000): 


to open the Account Schedule, then use the Acc. Schedule 


eo Note: In prior versions using Account Schedules, it was necessary 
Overview to preview the results. 
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€  M-BALANCE 


Financial Report | Ø Search Home Column Period Export to Excel More options 


M-BALANCE - Balance Sheet - M-BALANCE - M-BALANCE 


Options 


View by Day Show All Lines 


Date Filter 04/11/22 


Dimensions 


Department Filter 1 G/L Budget Filter 


Customergroup Filter 


Description Balance 


76,549.23 
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Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID])])/balanceSheets 


Example GET Response (3 entities shown from a longer list): 


{ 


"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/APIBook/api/ 
v2.0/Smetadata#companies ({{companyID}})/balanceSheets", 
"value": 


{ 
"Qodata.etag": "W/N"JzES5OzIwNjISOTYzMDIIMDkyMzQ4NzIxOzAwOyc-N"", 
"id": "4f9d3all-df3a-edl1l-bbae-6045bd8e554a", 

lineNumber": 10000, 


Utile Wisse, 
"balance": 0, 
"lineType": "header", 


"indentatd onus) 
"dateFilter": "2024-05-30" 


"Qodata.etag": "W/N"JzEAOzg1NjQ2MDExMjOyOTCcwMDE2ODE 7MDA7Jw--N"", 
"id": "509d3all-df3a-edl1-bbae-6045bd8e554a", 
"lineNumber": 20000, 


"display": "Current Assets", 
"balance": 0, 
"lineType": "header", 


"imdentatd onus 
Wdaieeha termi 90) 22/4140) 560) UU 


"Qodata.etag": "W/N"JzIwOzEAMTEOOTI2MTMINDAwNzUINZzk1MTswMDsnN"", 
"id": "519d3all-df3a-edl1-bbae-6045bd8e554a", 
"lineNumber": 30000, 
Voisplay Cash, 
"balance": 76549.23, 
"lineType": "detail", 
"indentation": 2, 
"dateFilter": "2024-05-30" 
}, 


It is recommended to supply a Date Filter in the request URI to restrict the Balance Sheet 
to the time period you require. It must be a single date, even though “Date Filter” sounds like 
it would accept all manner of filtering. This gives you the Balance at Date. Example URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID]])/balanceSheets?$filter-dateFilter eq 2024-05-30 


CRUD Steps 


As this is report results data, there are no steps to take. It relies on transactional data. 
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Bound Actions 


No bound actions. 


No navigations. 


History 


No notable changes. 
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Chapter 11: Bank Accounts 


The Bank Account endpoint maps straight to the Bank Accounts in the Business Central 
system. 


Primary Key 


No. The number of the bank account. The field is 20 characters and 
alphanumeric. 


Field Map 


API JSON: 
{ 
"Qodata.etag": "W/\"JzIwOzE2NTMzODYINTgwMjc1NzOyMjY3MTswMDsn\"", 
"gm: "ms39d0189f-cddli-efl1-9f8b5-6045bde9ecó1T'" 
"number": "WWB-EUR", 
"displayName": "World Wide Bank", 
"lastModifiedDateTime": "2024-05-14T10:35:06.4372", 
"bankAccountNumber": "99-33-456", 
"blocked": false, 
"currencyCode": "EUR", 


"currencyId": "00000000-0000-0000-0000-000000000000", 
Waban CESSOSREOSSSIOTE 2m ASINI OUS 
"intercompanyEnabled": false 


BUSINESS CENTRAL ENTITY: 
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Bank Account Card 
GIRO - Giro Bank 


Bank Account Navigate Report More options 


$ Dimensions [À Statistics Comments Æ Contact 


General 


* Balance 


B Receivables-Payables 


Gl Statements E} Ledger Entries 


Show more 


No. [airo 


number | sis 


Bank Account No. 


Name 


[Giro Bank displayName 


Balance 


Bank Branch No. | 


Communication > 


Posting 


Currency Code 


Blocked 


Enable for Intercompany tr... 


Last Payment Statement No. 


Last Check No. 


Payment Reconciliation No... 


Last Statement No. 


| 
| 
Transit No. | 
| 


Balance Last Statement 


Bank Acc. Posting Group 


Transfer 


Transit No. 


Bank Statement Import Fo... 


SWIFT Code 


Payment Export Format 


IBAN 


Como nes 


[14-55-678 bankAccountNumber | 


0.00 


(e » blocked 
( )| intercompanyEnabied 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 


nies(((companyID]])/bankAccounts 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID]])/bankAccounts (4bd018 9f-dd11-ef11-9f8b-6045bde9ccé1) 


Example GET Response (list): 


1 
"Qodata.context": 
panyID)])/bankAccounts", 
values: 


"http://bcserver: 7048/bc/api/v2.0/Smetadata#companies ({ {com 
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PAGE 


"Qodata.etag": "W/\"JzE40zkyODASNDQyMTgyNTc5OTkK3NDE7MDA7Jw==\"", 
"id"; "A4bd0189f-ddl1-ef11-9f8b-6045bde9cc61", 


Whappbadoxexe Ug. MEE O)M 

"displayName": "Giro Bank", 

"lastModifiedDateTime": "2024-05-14T10:35:06.4732", 
"bankAccountNumber": "14-55-678", 

"blocked": false, 

"currencyCode": "GBP", 


"currencyId": "00000000-0000-0000-0000-000000000000", 
Wages. Weder (NU) ROS Aegis OE TTE SITE 
"intercompanyEnabled": false 


"Qodata.etag": "W/N"JzE5OzOxMTk5MjUxMzUOMzI2NDYyODcxOzAwOyc-N"", 
Wael MW sieyslojilisseue—olclil curio Slovclssieersil Lor 


"number": "NBL", 

"displayName": "New Bank of London", 
"lastModifiedDateTime": "2024-05-14T10:36:40.822", 
"bankAccountNumber": "78-66-345", 

"blocked": false, 

"currencyCode": "GBP", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
MIDAS : "W n 


"intercompanyEnabled": false 
), 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID]])/bankAccounts 


Example POST Request Body: 


Migibpmlorese ^p - Miele Eur 
"displayName": "PayPalBusiness" 


Example POST Response: 


{ 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/Smetadata#companies ({ {com 
panyID}}) /bankAccounts/Sentity", 

"Qodata.etag": "W/N"JzIwOzEOMzY5NzAyOTA3Nzg4NzUANjgOMTswMDsnN"", 

"id": "39c33bb2-831e-ef11-be95-f60edc7f3ee3", 

"number": "PAYPAL", 

"displayName": "PayPalBusiness", 

"lastModifiedDateTime": "2024-05-30T12:54:06.4472", 

"bankAccountNumber": "", 

"blocked": false, 

Ucunsreneve, ode NN GEDPI 

"currencyId": "00000000-0000-0000-0000-000000000000", 

"Iipan" : "W JP 

"intercompanyEnabled": false 
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PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({{companyID}}) /bankAccounts (39c33bb2-831e-efl11-be95-f60edc7f3ee3) 


Example PATCH Request Body: 


"displayName": "PayPal - Business (EU)" 


Example PATCH Response: 


{ 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/Smetadata#companies (( {com 
panyID}}) /bankAccounts/Sentity", 

"@odata.etag": "W/\"JzIwOzEOMzY5NzAyOTA3Nzg4NzU4NjgOMTswMDsn\"", 

"id": "39c33bb2-831e-efll-be95-f60edc7f3ee3", 

"number": "PAYPAL", 

"displayName": "PayPal - Business (EU)", 

"lastModifiedDateTime": "2024-05-30T12:54:06.4472", 

"bankAccountNumber": "", 

"blocked": false, 

veurrencycodet NM SED 

"currencyId": "00000000-0000-0000-0000-000000000000", 

"ibam 5 "W ue 

"intercompanyEnabled": false 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({{companyID}}) /bankAccounts (39c33bb2-831e-efl11-be95-f60edc7f3ee3) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Actions 


CREATING 


Via the Action Bar in the Bank Accounts list, click the New button: 
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Bank Accounts: All | (© Search --New Ú De 


No. t Name 


CHECKING : World Wide Bank 


SAVINGS World Wide Bank 


Consult with your BC team about which number and other settings will be useful. The No. 
field is alphanumeric, so you can add accounts like ZZZ-TESTO1. 
UPDATING 
To trigger an Update of a G/L Account, the safest and simplest method to trigger an 
update is to alter the Name field. 
DELETING 


Bank Accounts can be deleted but ensure that it is an Account with no transactions 
associated with it. 


Bound Actions 


No bound actions. 


No navigations. 


| Version Changes 


23.0 Added bankAccountNumber, blocked, currencyCode, currencyld, iban, and 
intercompanyEnabled. 
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Chapter 12: Cash Flow Statements 


Being a financial accounting system, Business Central has many ways to get different key 
reports out of the system. The Cash Flow Statement endpoint is one way to obtain the data 
that underly one of the core financial reports. 


The Cash Flow API is pulled from the Financial Reports system. The Financial Report used 
can be configured in the Reporting section of the General Ledger Setup: 


General Ledger Setup 


General Posting Tax Bank Journal Templates 


Reporting 


Financial Report for Balance Sheet | M-BALANCE 


Financial Report for Income Stmt. M-INCOME 


Financial Report for Cash Flow Stmt. M-CASHFLOW 


Financial Report for Retained Earn. M-RETAIND 


The Financial Report for Cash Flow Stmt. controls the results. However, unlike a full 
Financial Report, only the Net Change column will be returned regardless of how many 
columns are defined. 


Note: The Financial Reporting area of the Business Central 
system is known by Account Schedules in prior versions. 
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Primary Key 


N/A 


This API is a query that does not directly expose a table, so there is no 
Business Central primary key. Each record in the results will be unique 
per Financial Report Line. 


Field Map 


API JSON: 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 


/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /cashFlowStatements/Sentity", 


"@odata.etag": "W/N"JzE5OzI2NDg20DEOMjOxMDUzMTI2MDYxOzAwOyc-N"", 
"id": "909d3all-df3a-edl11-bbae-6045bd8e554a", 
"lineNumber": 20000, 


Vdasplay" = “Net imecome™, 
"netChange": 30182.36, 
"lineType": "detail", 


"indentation": O0, 
"dateFilter": "2024-05-30" 


BUSINESS CENTRAL ENTITY: 


The easiest way to see the results of the Cash Flow Statements output is to open the 
Financial Report that is set to the the Financial Report For Cash Flow Stmt. from the General 
Ledger Setup. 


Note: In prior versions using Account Schedules, it was necessary 
to open the Account Schedule, then use the Acc. Schedule 


Overview to preview the results. 


In the example above, the example row is the 2" line (20000 divided by 10000): 
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M-CASHFLOW - M-NETCHANG 


Acc. Schedule Overview J Search Process Column Period More options 


General 


Account Schedule Name M-CASHFLOW tes Date Filter 01/01/22..12/31/22 


Column Layout Name M-NETCHANG d Show All Lines @ Off 


View by Year 


Dimension Filters Show more 


Department Filter ess G/L Budget Filter 


Customergroup Filter 


Description Net Change 


Operating Activities 


Net Income 17,468.91 


Be aware that you are looking at Net Change for Business Central, so the Date Filter on 
the BC Acc. Schedule Overview must comprise a range of dates, as does the API URI. 


If you do not provide a Date Filter, the Cash Flow Statement endpoint assumes you want 
to filter on Today only! 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]])/cashFlowStatements 


Example GET Request URI List with Date Filter: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/cashFlowStatements?$filter=dateFilter ge 2022-05-01 and 
dateFilter le 2024-05-30 


Example GET Response (2 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/cashFlowStatements", 
"value": [ 


{ 


"Qodata.etag": "W/N"JzE5OzMAMjc3MzExMj Y2MjQwMTE5MzYxOzAwOyc=\"", 
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"id": "8f9d3all-df3a-edl1-bbae-6045bd8e554a", 
"lineNumber": 10000, 


Vodaspilay = Op ealsumgmeetvesteite s 
"netChange": O0, 
"lineType": "header", 


"indentatd onu 
Vidalitelavliten Hg 0) AL 055—150) U/ 


"Qodata.etag": "W/N"JzESOzI2NDg20DEOMjQxMDUzMTI2MDYxOzAwOyc-N"", 
"id": "909d3all-df3a-edl1-bbae-6045bd8e554a", 
"lineNumber": 20000, 


"daspilayit- “Net income, 
"netChange": 30182.36, 
"lineType": "detail", 


"indentation": O0, 
"dateFilter": "2024-05-30" 
), 


CRUD Steps 


This is a read-only endpoint which exposes the results of a report. No actions in Business 
Central are possible to directly change the data that will be displayed in this report. 


Bound Actions 


No bound actions. 


No navigations. 


History 


No notable changes. 


PART 2: FINANCIALS ENDPOINTS 
CHAPTER 12: CASH FLOW STATEMENTS 


Chapter 13: General Ledger Entries 


This endpoint is pulled from the posted General Ledger Entries directly. This means there 
can be a huge amount of data, so you must filter your requests carefully! 


Note: With this endpoint, a large amount of data is available, so it 
is key to consider using smart $£ilter and $select options. 
See Part 8: Chapter 89: Performance (page 511) and Part 1: 
Chapter 2: Reading / GET (page 17) for more information. 


Primary Key 


Entry No. Integer identifier. 
Field Map 
API JSON: 
{ 
"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({{companyID}}) /generalLedgerEntries", 
"value": [ 


{ 
"Qodata.etag": "W/\"JzE50zcwNDMyNjk1MjYwNDI5NDkOMzIxOzAwOyc=\"", 
"id": "f5d19020-9efc-ee11-9f8c-6045bde98cOf", 
"entryNumber": 1, 
isOpemne Deca gg 207 (s que 


"documentNumber": "PS-INV103001", 

ddocumemnmtiype n E0070 , 

"accountId": "817df4e9-9dfc-eell-9f8c-6045bde98cOf", 
"accountNumber": "14130", 

Videscriprlont Direct Coet 20000 om (0057/3079 SM 


"debitAmount": O0, 

"creditAmount": 128.4, 
"additionalCurrencyDebitAmount": 0, 
"additionalCurrencyCreditAmount": 0, 
"lastModifiedDateTime": "2024-04-17T09:37:39.8772" 


PART 2: FINANCIALS ENDPOINTS PAGE 
CHAPTER 13: GENERAL LEDGER ENTRIES 


BUSINESS CENTRAL ENTITY: 


The General Ledger Entries list (shown here with some personalizations to fit the API 
columns) aligns with the API results: 


You will note that the BC Page has a single column called Amount., which is a different 
column from the debitAmount and creditAmount columns referenced in the API. Business 
Central's General Ledger Entry records have the following: 


e Amount 
e Credit Amount 
e Debit Amount 


The Credit/Debit Amount columns are either 0 (zero) or the relevant amount for the given 
Amount when used as a negative/positive; it depends on whether the G/L Account No. is a 
Balance Sheet or Income Statement type account. 


Additionally, in version 23.0, the additional currency version of those fields were also 
added. 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/generalLedgerEntries 


Example GET Request URI Single Account Filtered for just the March entries: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/generalLedgerEntries?$filter-(postingDate ge 2023-01-01) and 
(postingDate le 2023-03-31) and (accountNumber eq '14130') 


Example GET Response (2 example entries of a longer list): 


{ 


"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({{companyID}}) /generalLedgerEntries", 
"value": [ 
{ 
"Qodata.etag": "W/N"JzE5OzcwNDMyNjk1MjYwNDISNDkOMzIxOzAwOyc-N"", 
"id": "f5d19020-9efc-ee11-9f8c-6045bde98c0f", ) 
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"entryNumber": 1, 
WSOSeline Deca S W202 — d ys 


"documentNumber": "PS-INV103001", 

clo umen c0 00M 

"accountId": "817df4e9-9dfc-eell-9f8c-6045bde98cO0f", 
"accountNumber": "14130", 

udesei bronce St 2000/0 om ON 1877 22/9" 


"debitAmount": O0, 

"creditAmount": 128.4, 
"additionalCurrencyDebitAmount": 0, 
"additionalCurrencyCreditAmount": 0, 


"lastModifiedDateTime": "2024-04-17T09:37:39.8772" 
Ie 
{ 
"@odata.etag": "W/\"JzIwOzE1LODAwMTgzMjE2NjU20DYZNjg2MTswMDsn\"", 
"id": "15d29020-9efc-ee11-9f8c-6045bde98c0f", 
"entryNumber": 10, 
JsyoxenEsusKelDEeuEU S WS 1 eU 
"documentNumber": "PS-INV103002", 
clo cumentssvo cO NU 
"accountId": "817df4e9-9dfc-eell1-9f8c-6045bde98cOf", 
"accountNumber": "14130", 
Wideseription aUe Cose MOCO om OU 159/229 
"debitAmount": O0, 
vereditAmount S: (6012, 
"additionalCurrencyDebitAmount": 0, 
"additionalCurrencyCreditAmount": 0, 
"lastModifiedDateTime": "2024-04-17T09:37:41.0832" 
}, 
eal 
CRUD Steps 
CREATING 


General Ledger Entries are generated by any financial transaction posted in the system. 
The simplest way to add a new entry is to create and post a General Journal set of lines that 
makes a minor adjustment and reversal against the same account, as follows: 


Manage Home Request Approval Payroll Line Incoming Document Page More options 


lif Post | v [8 Get Standard Journals... E} Renumber Document Numbers [3] Reconcile &^A 


Document Account 
Posting Date Type Document No Type Account No. Description Amount Amount ($) ^ Account Name 


4/11/2022 G00001 G/L Account 40300 Sales Discounts 1.00 1.00 Sales Discounts 
4/11/2022 G00001 G/L Account 40300 Sales Discounts -1.00 -1.00 Sales Discounts 


Bound Actions 


No bound actions. 


e accounts (page 38) 
e attachments (page 378) 
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e dimensionSetLines (page 427) 


23.0 Fields Added: lastModifiedDateTime, additionalCurrencyDebitAmount, 
additionalCurrencyCreditAmount 
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Chapter 14: General Ledger Setup 


This endpoint is used to get setup data from the General Ledger Setup record. 


Primary Key 


Primary Key Alphanumeric 10 character code field. Since this is a setup record, there 
should be only one record in the table. 


Field Map 


API JSON: 
1 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/Smetadata#companies (( (com 
panyID}}) /generalLedgerSetup", 

"value": [ 


{ 
"@odata.etag": "W/N"JzE5OzUOMDYwNDA3Njk3Mjc2NDg3NDgxOzAwOyc-N"", 
"rg fbi a2 099 dd e RN 9E ato075bde9eeodN 


Wed Tivletoxstese step Eroma. VOOM LOO 

"Ure lbIbeieteyenestoxgato s VWOO@il— WALL 
"additionalReportingCurrency": "", 
"localCurrencyCode": "GBP", 

HilOcCalCumnency oymb ol E 
"lastModifiedDateTime": "2024-05-14T10:36:03.882", 


"allowQueryFromConsolidation": false 


BUSINESS CENTRAL ENTITY: 
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General Ledger Setup 


Home Posting General 


Tax Bank Journal Templates 


EF Change Payment Tolerance Že Change Global Dimensions. 


General 


US dollar 


City+State+ZIP Code 


[After Company Name 


Nearest 


Bill-to/Pay-to No. 


Example GET Request URI List: 


Interes) o J/ apii 


businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 


nies ({{companyID}}) /generalLedgerSetup 


Example GET Request URI Single: 


https://api. 


businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 


nies(((companyID)])/generalLedgerSetup(1c15971e-df3a-ed11-bbae-6045bd8e554a) 


While specifying a record is possible, there should only be one setup record in the table 
at any given time. 


Example GET Response : 


{ 
"@odata. 


context": "http://bcserver:7048/bc/api/v2.0/Smetadata#companies ({ (com 


panyID}})/g 
"value": 


{ 


neralLedgerSetup", 
[ 


"Qodata.etag": "W/N"JzE5OzUOMDYwNDA3Njk3Mjc2NDg3NDgxOzAwOyc-N"", 
"gm e tbia2099-dadd eti -9tebozo)045bde9ecióT 


We loves ting Enom- aO (0) 15169) dl. 7 
We iow osre os MIO (0): W 
"additionalReportingCurrency": "", 
"localCurrencyCode": "GBP", 
Wwlocal@urrencyoymbole: CE, 


"lastModifiedDateTime": "2024-05-14T10:36:03.882", 
"allowQueryFromConsolidation": false 
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CRUD Steps 


CREATING 


This data is a core record in Business Central, and therefore should automatically be 
created. 


UPDATING 


Any changes to fields should trigger an update. For example, “Allow Posting From". 


DELETING 


Business Central prevents deletion of this record. 


Bound Actions 


No bound actions. 


Navigation 


No navigations. 


History 


| Version Changes 


23.00 Added. 
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Chapter 15: Income Statements 


Being a financial accounting system, Business Central has many ways to get different key 
reports out of the system. The Income Statement endpoint is one way to obtain the data that 
underly one of the core financial reports. 


The Income Statements API is pulled from the Financial Reports system. The Financial 
Report used can be configured in the Reporting section of the General Ledger Setup: 


General Ledger Setup 


General Posting Tax Bank Journal Templates 


Reporting 


Financial Report for Balance Sheet M-BALANCE 


Financial Report for Income Stmt. M-INCOME 


Financial Report for Cash Flow Stmt. M-CASHFLOW 


Financial Report for Retained Earn. M-RETAIND 


The Financial Report For Income Stmt. controls the results. However, unlike a full 
Financial Report, only the Net Change column will be returned, regardless of how many 
columns are defined. 


Note: The Financial Reporting area of the Business Central 
system is known by Account Schedules in prior versions. 
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Primary Key 


N/A This API is a query that does not directly expose a table, so there is no 
Business Central primary key. Each record in the results will be unique 
per Financial Report Line. 


Field Map 


API JSON: 
{ 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/Smetadata#companies (( {com 
panyID}})/incomeStatements", 

"value": [ 


{ 


"Qodata.etag": "W/\"JzE40zM2Nzk3MDY 4MDA4MDU2NDg2NTE7MDA7Jw==\"", 
"id": "5135e7e6-dd1l-ef11-9f8b-6045bde9cc61", 
"lineNumber": 10000, 


Wdasplay =. Vincome yy, 
"netChange": O0, 
"lineType": "header", 


"indentation": O0, 
Vdaltehi iter G20 24-05-30 
}, 


BUSINESS CENTRAL ENTITY: 


The easiest way to see the results of the Income Statements output is to open the 
Financial Report that is set to the the Financial Report For Income Stmt. from the General 
Ledger Setup. 


Note: In prior versions using Account Schedules, it was necessary 
to open the Account Schedule, then use the Acc. Schedule 


Overview to preview the results. 


In the example above, the example row is the 3" line (30000 divided by 10000): 
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CRONUS USA) € = w-income 
| 


Financial Reporting: 
be af Financial Report Ø Search Home Column Period Export to Excel More options 


Name t © Recalculate — €» Restore to default filters — W9Print.. 
ACC-CAT E M-INCOME - Income Statement - M-INCOME - M-NETCHANG 
ANALYSIS 

CASHFLOW pons 

| CACYCLE View by Day v Show All Lines 
I. CASHFLOW 


Date Filter 01/01/22..04/22/22 | 


| INCEXP. 
I MINTRIAL 


Dimensions Show more 


M-BALANCE 


M-CASHFLOW Department Filter vex G/L Budget Filter et 


M-INCOME Customergroup Filter 
M-RETAIND 


REVENUE 


Description Net Change 


Income 


Income, Services -29,132.97 


Be aware that you are looking at Net Change for Business Central, so the Date Filter on 
the BC Acc. Schedule Overview must comprise a range of dates, as does the API URI. 


If you do not provide a Date Filter, the Income Statement endpoint assumes you want to 
filter on Today only! 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /incomeStatements 


Example GET Request URI List with Date Filter: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/incomeStatements?$filter=(dateFilter ge 2023-01-01) and 
(dateFilter le 2023-04-24) 


Example GET Response (3 entities shown from a longer list): 


{ 


"Qodata.context": "http://bcserver:7048/bc/api/v2.0/Smetadata#companies ({ {com 
panyID}})/incomeStatements", 
"value": [ 


{ 
"Qodata.etag": "W/\"JzIwOzEONDIxODU4MjI4MjA5Njk1MjI2MTswMDsn\"", 
"id": "5135e7e6-dd1l-ef11-9f8b-6045bde9cc61", 
"lineNumber": 10000, 
vaisplay s Vincomell, 
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"netChange": O0, 
"lineType": "header", 
WindemcatLon si 0, 

Vidateni ited t WZ 0238-04-24 


"Qodata.etag": "W/N"JzIwOzE2MTY2OTAONzM3NDUyOTCAMjE5MTswMDsnN"", 
"id": "5235e7e6-ddll-ef11-9f8b-6045bde9cc61", 
"lineNumber": 20000, 


"display income, Servi cesty 
"netChange": O0, 

"lineType": "detail", 
“indentation: e 
"dateFilter": "2023-04-24" 


"Qodata.etag": "W/N"JzIwOZzExNDYA4NzMIMDES5NTM3MjExNDcxMTswMDsnN"", 
Wig Mossbe7eo-ddll—erlil— 9fa8b5-o045bde9ccil] 
"lineNumber": 30000, 


"ispila y UC ome Poncius ale 
"netChange": O0, 
"lineType": "detail", 


vindentatciriont: 17 
"dateFilter": "2023-04-24" 
}, 


[el 
CRUD Steps 


This is a read-only endpoint which exposes the results of a report. No actions in Business 
Central are possible to directly and simply change the data that will be displayed in this report. 


Bound Actions 


No bound actions. 


No navigations. 


No notable changes. 
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Chapter 16: Journals 


Despite the name, this Journal endpoint refers to the Business Central Journal Batch 
information for General Journal Templates of the General Type. 


For non-Business Central people, Journal Batches are worksheets of Journal Lines. The 


structure is along these lines: 


Journal 


eControls Pages/Reports used 


Template 


Journal *Allows Multiple sets of 
users to work with 


Batch journal lines 


Journal 


Lines 


Journal Templates allow users to post different types of journals, such as payments made 
out, cash receipts, and others. 


Journal Batches are functionally like Excel worksheets, just a means of keeping records 
separate, posting them separately. 


This endpoint allows you access to this Journal Batch list and the related records. 


Important: Journal Template Filter 
v17 and up: 


You may supply a filter for the templateDisplayName field to change which Journal 
Template you wish to use. If nothing is specified, it will use the pre-v17 defaulting logic. 


Pre-v17: 


This endpoint has a built-in filtering logic. Because the Journal Batch is a subset of Journal 
Templates, the system must either ask you for a Journal Template to use or have a means built- 
in to decide. 
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The current method in the product is that it decides for you. It does this by: 


e Of all the General Journal Templates (non-Recurring) 
e That are of Type General 
e Whichever is first (alphabetically) 


This means that if your Business Central company has multiple Journal Templates like the 
example here: 


General Journal Templates v/ Saved 


J9 Search -+ New EZ Edit List li] Delete Related ^» Automate v Fewer options 


Bal. Account Bal. Account 
Name f Description Type - Type No. No. Series 


ASSETS Fixed Asset G/L Journal Assets G/L Account FA-JNL 
CASHRCPT Cash receipts Cash Recei... G/L Account GJNL-RCPT 
GENERAL GENERAL General G/L Account GJNL-GEN 


IC-REVENUE Intercompany Revenue General G/L Account GJNL-GEN 


You can see two Templates, GENERAL and IC-REVENUE, defined as Type of General. All 
calls to the Journal endpoint will use the Journal Batches defined only for the Template 
GENERAL. The IC-REVENUE batch will be inaccessible. 


Primary Key 


Journal Template Name | The name of the Journal Template. The field is 10 characters 
and alphanumeric. 

Name The name of the Journal Batch. The field is 10 characters and 
alphanumeric. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/APIBook/api/ 
v2.0/Smetadata#companies ({{companyID}})/journals/Sentity", 

"@odata.etag": "W/N"JzIwOzE2NjcyNjYwNDIxMTA3MTOzNTM5MTswMDsnN"", 

"id": "6cl140db7-dd1l1l-ef11-9f8b-6045bde9cc61", 


"code": "DEFAULT", 

"displayName": "Default Journal Batch", 
"templateDisplayName": "GENERAL", 
"lastModifiedDateTime": "2024-05-14T10:36:57.6172", 


"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "" 
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BUSINESS CENTRAL ENTITY: 


= General Journals 


Batch Name DEFAULT E 


Manage Home Request Approval Payroll Line Incoming Document Page Actions ~ Related ~ 


Automate ~ 


Document Account 
Posting Date Type Document No. Type Account No. Account Name 


4/11/2022 * G/L Account 


Description 


General Journal Batches D +New Edit List 


Bal. Account 
Name t Descnption 


Type No 


> DEFAULT : Default Journal Batch G/L Account 


MONTHLY Monthly Journal Entries G/L Account 10100 GJNL-GEN 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/journals 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/journals (6c140db7-dd11-ef11-9f8b-6045bde9cc61) 


Example GET Response: 


{ 


"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/APIBook/api/ 
v2.0/Smetadata#companies ({{companyID}})/journals/Sentity", 

"@odata.etag": "W/N"JzIWOzE2NjcyNjYwNDIxMTA3MTOzNTM5MTswMDsnN"", 

"nigga comedi eti oR9p-045sae9ce6lN 

"code": "DEFAULT", 

"displayName": "Default Journal Batch", 

"templateDisplayName": "GENERAL", 

"lastModifiedDateTime": "2024-05-14T10:36:57.6172", 

"balancingAccountId": "00000000-0000-0000-0000-000000000000", 

"balancingAccountNumber": "" 
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Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/journals 


Example POST Request Body: 


"code"; "Temporary", 
"displayName": "Temporary Journal Entries" 


Example POST Response: 


{ 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/Smetadata#companies ({ {com 
panyID}})/journals/Sentity", 

"Qodata.etag": "W/N"JzE5OzM2Njg2MjOwMDIyMDCINTkzNzMxOzAwOyc-N"", 

"id": "d94037fb-851e-efll1-be95-f60edc7f3ee3", 


"code": "TEMPORARY", 

"displayName": "Temporary Journal Entries", 
"templateDisplayName": "GENERAL", 
MilacstModutaedDakelimen:s — 0779)2/21—(0]15)—5 5(0)2t 1L S8 3110) 8:2: EH 7 


"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/journals (78adef10-8750-ed11-946f-000d3a8dcb22) 


Example PATCH Request Body: 


"displayName": "Very Permanent Journal Entries" 


Example PATCH Response: 


{ 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/Smetadata#companies (( {com 
panyIDjj)/journals/S$entity", 

"Qodata.etag": "W/N"JzE5OzM2Njg2MjOwMDIyMDCINTkzNzMxOzAwOyc-N"", 

"id": "d94037fb-851e-efl1-be95-f60edc7f3ee3", 


Uode ATEMPORAR 

"displayName": "Very Permanent Journal Entries", 
"templateDisplayName": "GENERAL", 
"lastModifiedDateTime": "2024-05-30T13:10:27.612", 


"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "" 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 


nies((companyID)])/journals (d94037fb-851e-efll1-be95-f60edc7f3ee3) 


No request body is required. No response body will be given, only an HTTP Status of 204, 


"No Content." 


CRUD Steps 


CREATING 


As General Journal Batches are a subset of Journal Templates, the Journal Batches can 
be found on the General Journal Templates page under the Action Bar's Related -» Template 


-» Batches (with the appropriate Template selected): 


General Journal Templates 


Ø Search - New  BEEditlist [i] Delete 


| Related ^^ Automate v 


Fewer options 


K] Template > [aed Batches 


Bal. Account Bal. Account 
Name f Description Type Rec... Type No. 


— ASSETS Fixed Asset G/L Journal Assets G/L Account 


CASHRCPT 
GENERAL 


Cash receipts Cash Recei... G/L Account 


GENERAL General G/L Account 


This opens the editable list of General Journal Batches: 


General Journal Batches Ø Search + New E Edit List ij Delete 


Bal. Account 


Name f Description Type 


— | DEFAULT Default Journal Batch G/L Account 


Postin: 
No. Series Series 


FA-JNL 
GJNL-RCPT 


GJNL-GEN 


Home Er Post 


No. Series 


FA-JNL 


Click New to create a new entry and manually enter an Alphanumeric Name. 


UPDATING 


The safest and simplest method to trigger an Update of a General Journal Batches is to 


alter the Description field. 
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DELETING 


General Journal Batches can be deleted. However, be aware that this will delete all 
related General Journal Lines that still need to be posted. 


Bound Actions 


No bound actions. 


e accounts (page 38) - this should return the account endpoint for the Bal. Account 
No. of the Batch. However, it does not work. (See Part 8:Chapter 91: API Bugs, 
page 517) 

e journalLines (page 76) 


Changes 


templateDisplayName was added as a new field, as well as support for filtering 
on it to access alternate Journal Templates 
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Chapter 17: Journal Lines 


This endpoint allows access to the General Journal Lines for a given batch. While this 
Endpoint exposes the Journal Line creation, there is an important limitation! 


Business Central supports Account Types (and Balance Account Type) of: 


G/L Account 
Bank Account 
Customer 
Vendor 

IC Partner 
Fixed Asset 
Employee 


Only the G/L Account and Bank Account types are accepted by this API endpoint. 


Primary Key 


Journal Template Name The name of the Journal Template. The field is 10 


characters and alphanumeric. 


Journal Batch Name The name of the Journal Batch. The field is 10 characters 


and alphanumeric. 


Line No. It is a system-assigned integer. Typically, this is created in 
increments of 10000 so lines may be inserted between 
other records. 

Field Map 

API JSON: 
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{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /journals (2f5a2523-df3a-edl1- 
bbae-6045bd8e554a) /journalLines/Sentity", 

"Qodata.etag": "W/\"JzIwOzE3MzA3MzU4NzkyMzA1MTQWMDQOMTswMDsn\"", 

"id": "23786bdc-16a0-ed11-9a8a-6045bd02aa7a", 

"journallId": "2f5a2523-df3a-edll-bbae-6045bd8e554a", 

"journalDisplayName": "DEFAULT", 

"lineNumber": 10000, 

"accountType": "G x002F L x0020 Account", 

"accountId": "2115971e-df3a-edll-bbae-6045bd8e554a", 

"accountNumber": "10400", 

WAS Eo Dees NAO 2 (Qaa Wer 

"documentNumber": "TESTOI", 

"externalDocumentNumber": "", 

JettexbustEP S 0, 

"description": "Accounts Receivable", 

"comment": LLS u 

"taxCode": "NONTAXABLE", 

"balanceAccountType": "G x002F L x0020 Account", 

"balancingAccountId": "1e15971e-df3a-edll-bbae-6045bd8e554a", 

"balancingAccountNumber": "10100", 

AlieienglntoxeatieabexelibieuecMesbars s: 177(0)2 9 (91:5 SO 481b 2:8 OSes 2:9) SS sya 


BUSINESS CENTRAL ENTITY: 


General Journals 


Batch Name DEFAULT journalDisplayName 


Manage Line A$ £ Page Actions Related 


sting Date pe jocument No pe Account N Account Name 
4/11/2022 Payment TESTO1 G/L Account 10400 Accounts Receivable Accounts Receivable 


4/11/2022 + Payment TESTO2 G/L Account 10200 Saving account Saving account 


Amount ($ 
4/11/2022 NONTAXABLE 0.00 G/L Account 
4/11/2022 : NONTAXABLE 0.00 | G/L Account 


Posting Date 


4/11/2022 G/L Account 
4/11/2022 : /L Account 


There are two additional fields in the JSON that are either hidden or complex. 


The externalDocumentNumber is hidden and must be shown via the Personalize 
option in the menu bar: 
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Environment 


C APIBook 


Settings 


Dynamics 365 Business Central 
Personalize 

Design 

My Settings 

Company information 

Assisted setup 

Advanced settings 

Admin Center 


The External Document No. Field can be dragged to the page layout: 


Dynamics 365 Business Central 


Personalizing: General Journals 


^ Add Field to Page 


Place held; by dragging from the list to 2 


Journal Line Details 


> Add Field to Page 


Place fields by dragging from the list to a 
position on the page. 


p 
Bank Payment Type Ready ^ 


Date 


Document Date Ready 


Code | externalDocumentNumber 


External Document No. Ready 


The taxCode field is complex, as it maps to one of two fields. If the Business Central 
system is configured to Use VAT, this field is mapped to the VAT Prod. Posting Group field, 
which can be shown in the UI via Personalize. The field is mapped to the Tax Group Code if 
the system is configured not to Use VAT. 
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This setting is driven by the Localization system and depends on the region for which the 
Business Central system is configured. 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /journals (2£5a2523-df3a-ed11-bbae-6045bd8e554a) /journalLines 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/journals (2£5a2523-df3a-edl11- 
bbae-6045bd8e554a) /journalLines/Sentity", 

"Qodata.etag": "W/N"JzE5OzMzODQ10DgyOTO1MDQ3OTYyMjExOzAwOyc-N"", 


"id": "67910bcf-dece-ec11-8373-e8746cfafddb", 
"journalId": "76091978-a1a6-ec11-8370-8cc96a41ed4e", 
"journalDisplayName": "DEFAULT", 

"lineNumber": 10000, 

"accountType": "G x002F L x0020 Account", 
"accountId": "f2c92172-al1a6-ec11-8370-8cc96a41ed4e", 
"accountNumber": "2340", 

VpOst lng Datse mt 2 022 — OA s Men 

"documentNumber": "TESTOL", 
"externalDocumentNumber": "", 

meum ca Oy, 

"description": "Other Receivables", 

"comment" 8 "W u 

"traxcode" : us. 

"balanceAccountType": "G x002F L x0020 Account", 
"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "", 
wiacsteMod ited bDatelimet: st 022 OO FTIV SIS Olom NON 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/journals (2£5a2523-df3a-ed11-bbae-6045bd8e554a) /journalLines 


Example POST Request Body: 


"accountNumber": "10400", 
“poseingpatet 3 29) 2 0 (0555 si0)4 
"documentNumber": "12345", 
"externalDocumentNumber": "67890", 
WAMOuMtw = (O0) c. (9)0- 

"description": "Sample", 

"W comment" 8 nw 
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Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/journals (2f5a2523-df3a-edl1- 
bbae-6045bd8e554a) /journalLines/Sentity", 

"@odata.etag": "W/N"JzIwOzEwMTCOMzUzNTIANTCyMDkyMDY5MTswMDsnN"", 

"id": "99ff9ec4-61d3-ec11-8374-ec6451d2e18b", 

"journalId": "76091978-a1a6-ec11-8370-8cc96a41ed4e", 


"journalDisplayName": "DEFAULT", 

"lineNumber": 30000, 

"accountType": "G x002F L x0020 Account", 
"nmaccountIid*-Ur2co272-a]a60-ecd0-990:9cc9060a4ded4e' 
"accountNumber": "10400", 

Jieroyenesusvejbevec Mg WAP Os— S104 5 

"documentNumber": "12345", 

"externalDocumentNumber": "67890", 

amoun B. es LOO OO, 

Vdeseripezon" =) “Sample, 

Icommenti ae wey, 

Iota (86 clle g Un 

"balanceAccountType": "G x002F L x0020 Account", 
"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "", 


"lastModifiedDateTime": "2023-05-30T09:32:29.213Z" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/journals (2£5a2523-df3a-edl1-bbae- 
6045bd8e554a) /journalLines (99ff9ec4-61d3-ec11-8374-ec6451d2e18b) 


Example PATCH Request Body: 


"accountNumber": "2340", 
Voostingbatwel 2024 5 
"documentNumber": "12345", 
"externalDocumentNumber": "67890", 
Jeune sg cibis 

"description": "Sample Update", 
commentis ui 


Example PATCH Response : 


{ 
"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/journals (2f5a2523-df3a-edl1- 
bbae-6045bd8e554a) /journalLines/Sentity", 
"Qodata.etag": "W/\"JzE50zkxMDcyNzM5MjUxOTg5NzU1NDgxOzAwOyc=\"", 
mygmumoottoec4-olds-ecll-93y4-eceo4b5utd2et9»b"" 
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"journalId": "76091978-a1a6-ec11-8370-8cc96a41ed4e", 


"journalDisplayName": "DEFAULT", 

"lineNumber": 30000, 

"accountType": "G x002F L x0020 Account", 
"accountId": "f2c92172-al1a6-ec11-8370-8cc96a41ed4e", 
"accountNumber": "10400", 

"postingDate": "2024-05-30", 

"documentNumber": "12345", 

"externalDocumentNumber": "67890", 

amorim taea d52 5 s 00, 

"description": "Sample Update", 

"commernt" 8 LLS ma 

mMraxcoden g mu 

"balanceAccountType": "G x002F L x0020 Account", 
"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "", 
"lastModifiedDateTime": "2023-05-30T09:40:53.4692" 


} 
DELETE 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /journals (2£5a2523-df3a-edl1-bbae- 
6045bd8e554a) /journalLines (99ff9ec4-61d3-ec11-8374-ec6451d2e18b) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


As General Journal Lines are a subset of Journal Batches, you open the list of General 
Journal Batches: 


General Journals: J Search + New fii] Delete Ee Edit List Proci 


Name f Description Bal. Account Type Bal. Account No. 
DEFAULT : Default Journal Batch G/L Account 


MONTHLY Monthly Journal Entries G/L Account 


Click on the name of the batch, which will open the General Journal Lines: 
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General Journals 


Batch Name DEFAULT 


Manage Home Request Approval Payroll Line Incoming Document Page More options 


Document Account 
Posting Date Type Document No. Type Account No. Description Amount ($) 


4/11/2022 : TESTO1 G/L Account 10400 Accounts Receivable 0.00 
4/11/2022 TESTO2 G/L Account 10200 Saving account 0.00 


At a minimum, you will need the following: 


e To enter a Posting Date, Document No. Account Type, Account No. and Amount. 
e The Account can be the same. 
e The Amounts should sum to 0. 


UPDATING 


The safest and simpest method to trigger an Update of a General Journal Line is to alter 
the Description field. 


DELETING 


General Journal Lines can be deleted easily via the Delete action bar button. 


Bound Actions 


No bound actions. 


e accounts (page 38) - this will expand only if the Account Type is G/L Account. 
This will return null if the Account Type is Bank Account. No expand is possible 
on the Bal. Account No. 

e attachments (page378) 

e CustomerPaymentJournals (page 126) - This is technically possible because the 
General Journal Lines and the Customer Payment Journals use the same 
underlying tables, but for this endpoint, it will return null. 

e dimensionSetLines (page427) 

e journals (page 70) 
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Changes 
A defect was corrected in the logic for the Bal. Account No. that would always 


validate it as if it were Bal. Account Type of Bank Account. (See Part 8: Chapter 
91: API Bugs on page 517.) 
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Chapter 18: Retained Earnings Statements 


Being a financial accounting system, Business Central has many ways to get different key 
reports out of the system. The Retained Earnings Statement endpoint is one way to obtain 
the data that would underly one of the core financial reports. 


The Retained Earnings Statement API is pulled from the Financial Reports system. The 
Financial Report used can be configured in the Reporting section of the General Ledger Setup: 


General Ledger Setup 


General Posting Tax Bank Journal Templates 


Reporting 


Financial Report for Balance Sheet M-BALANCE 


Financial Report for Income Stmt. M-INCOME 


Financial Report for Cash Flow Stmt. M-CASHFLOW 


Financial Report for Retained Earn. M-RETAIND 


The Financial Report For Retained Earn. controls the results. However, unlike a full 
Financial Report, only the Net Change column will be returned, regardless of how many 
columns are defined. 
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Primary Key 


N/A This API is a query that does not directly expose a table, so there is no 
Business Central primary key. Each record in the results will be unique 
per Financial Report Line. 


Field Map 


API JSON: 
{ 
"Qodata.etag": "W/\"JzIwOzE20TMOMJE3NDcyMjcyNzIyODcwMTswMDsn\"", 
"id": "8e35e7e6-ddll-ef11-9f85b-6045bde9cc61", 
"lineNumber": 10000, 
"display": "Retained Earnings, Period Start", 
"netChange": O0, 
"lineType": "detail", 


"indentation": O0, 
"dateFilter": "2024-06-03" 


BUSINESS CENTRAL ENTITY: 


The easiest way to see the results of the Retained Earnings Statement output is to run the 
Acc. Schedule Overview page. Ensure the Account Schedule Name is set to the same value 
as the Acc. Sched. For Retained Earn. from the General Ledger Setup. 


In the example above, the example row is the 2"? line (20000 divided by 10000): 


PART 2: FINANCIALS ENDPOINTS 
CHAPTER 18: RETAINED EARNINGS STATEMENTS 


CRONUS USA) €  wnETAND 


Financial Reporti 
ng Financial Report Ø Search Home Column Period Export to Excel More options 


Name f © Recalculate © Restore to default filters 8 Print... 


ACC-CAT M-RETAIND - Retained Earnings - M-RETAIND - M-NETCHANG 
ANALYSIS 


CASHFLOW Options 


| CACYCLE i View by Day v Show All Lines 


| CASHFLOW Date Filter 01/01/22..04/24/22 


| INCEXP 
I MINTRIAL 


Dimensions Show more 
M-BALANCE 


M-CASHFLOW Department Filter aaa G/L Budget Filter Ball 


M-INCOME Customergroup Filter 
M-RETAIN, 


REVENUE 


Row No. Description Net Change 


Retained Earnings, Period Start 


Be aware that you are looking at Net Change for Business Central, so the Date Filter on 
the BC Acc. Schedule Overview must comprise a range of dates, as does the API URI. 


If you do not provide a Date Filter, the Retained Earnings endpoint assumes you want to 
filter on Today only! 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /retainedEarningsStatements 


Example GET Request URI List with Date Filter: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /retainedEarningsStatements?$filter=(dateFilter ge 2022-01-01) 
and (dateFilter le 2022-04-24) 


Example GET Response (2 entities shown from a longer list): 


{ 


"Qodata.context": "http://bcserver:7048/bc/api/v2.0/Smetadata#companies ({ {com 
panylID}}) /retainedEarningsStatements", 
"value": [ 


{ 
"Qodata.etag": "W/N"JzIwOzE20TMOMjE3NDcyMjcyNzIyODcwMTswMDsnN"", 
"id": "8e35e7e6-ddll-ef11-9f85b-6045bde9cc61", 
"lineNumber": 10000, 

"display": "Retained Earnings, Period Start", 
"netChange": O0, 
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"lineType": "detail", 


"indentation": 
"dateFilter": 


"@odata.etag": 


0, 
90/27 1—(15—(0)5) 4 


"W/N"JzE5OzQO0OTASNTYOMzQ2Njg4MDc2MjgxOzAwOyc-N"", 


"id"; "8f35e7e6-dd11-ef11-9f8b-6045bde9cc61", 


"lineNumber": 20000, 
"display": "Net Income", 
"netChange": O0, 
"lineType": "detail", 
"indentation": 0, 

aace miiiitert a 7910) 221—401) (0| sh) 


CRUD Steps 


As this is report results data, there are no steps to take. It relies on transactional data. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


History 


No notable changes. 
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Chapter 19: Trial Balances 


The Trial Balance endpoint is a way to obtain the data behind the Business Central report 
Trial Balance type of reports, which are all various views on the Chart of Accounts, the list of 
G/L Accounts. 


Since this endpoint exposes both the Net Change (total) and Balance (balanceAtDate) 
fields as debits and credits separately, the most beneficial report to compare against is the 
Trial Balance/Budget report, which also breaks out the debits and credits; however, only as a 
total result. So, 500 debit and 300 credit will display as only 200 debit. 


Primary Key 


No. The numeric identifier of the G/L Account for the line. The field is 20 
characters and alphanumeric. 


Field Map 


API JSON: 


1 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/trialBalances/Sentity", 
"Qodata.etag": "W/\"JzIwOzEwNDUxMzE1ODYIMTQWMDQ2Mzk2MTswMDsn\"", 
"accountId": "2015971e-df3a-ed11-bbae-6045bd8e554a", 


number w: TOSTO 

Waeccounmeypen Posti 
displays: Petty eash 

Wi Gta Debate: 88), OR sO, 
Wi@iealiGiee Gant! ONG 
"balanceAtDateDebit": "76,549.23", 
"balanceAtDateCredit": "0.00", 


“dateFilter™: "2022-04-24" 


BUSINESS CENTRAL ENTITY: 
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Trial Balance/Budget 


Period: 01/01/22..04/24/22 
CRONUS USA, Inc. 


G/L Account: Date Filter: 01/01/22..04/24/22 


Credit 


BALANCE SHEET 


ASSETS 
Checking account 
Saving account 
Petty Cash 


Accounts Receivable 


The accountType field is not included in most reports, but this is the same information 
from the G/L Account endpoint, as the report here lists the financial data by each G/L Account. 
The amounts are broken out in the API to give you debit and credit amounts separately. 


Important: You should supply a Date Filter to update the Net Change columns. Additionally, 
the Net Change will display the total transactions, whereas the report only displays the 
difference. In the above example, we can see that the 10300 account shows a Debit of 13,912. 
For the same account in the API, we get the following: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/trialBalances/Sentity", 
"Qodata.etag": "W/\"JzIwOzEwNDUxMzE1ODY1IMTQWMDQ2Mzk2MTswMDsn\"", 
"accountId": "2015971e-df3a-edl1l1-bbae-6045bd8e554a", 


orto ex: WALCO SOO, 

Waccountehypel: "Postings, 
tdisplay e MPetty Cashu, 
Wi@tealDebiie ss ugs OSE OQU 
WiceieeulCiceycline n Ua Weir 
"balanceAtDateDebit": "76,549.23", 
"balanceAtDateCredit": "0.00", 


"dateFilter": "2022-04-24" 


The totalDebit and totalCredit show the entire amounts. 88709.80 minus 74797.62, which 
gets us the 13912 (rounded) displayed in the report. 


However, the balanceAtDateDebit and balanceAtDateCredit will match the Balance 
columns in the report. 
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Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/trialBalances?S$filter-(dateFilter ge 2022-01-01) and 
(dateFilter le 2022-04-24) 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/trialBalances (2015971e-df3a-edll-bbae- 
6045bd8e554a) ?$filter=(dateFilter ge 2022-01-01) and (dateFilter le 2022-04-24) 


Example GET List Response (limited to 2 results): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({{companyID}})/trialBalances", 
"value": [ 


{ 
"Qodata.etag": "W/\"JzE50zUyNTM5MTM5MjA4NzUwOTM1NjMxOzAwOyc=\"", 
"accountId": "1c15971e-df3a-edl1-bbae-6045bd8e554a", 
"number": "10000", 


"accountType": "Heading", 
"display": "BALANCE SHEET", 
WigroneretliprstentiE eo. UU 

INeonec UCase ls WE. 
"balanceAtDateDebit": "", 
"balanceAtDateCredit": "", 


"dateFilter": "2022-04-24" 


"Qodata.etag": "W/N"JzIWOzE2NTI2NzIONzc3NzUxOTYxNzMAMTswMDsnV"", 
"accountId": "1d15971e-df3a-ed11-bbae-6045bd8e554a", 

Mormp esto RH ON RIT 
VeyexrerexbuduEdNqexe s! Hsec <O Rowell, 
"gllegseu a UNS. 

tEotalDepiit u WM 

Ueotaleredi etni AW. 
"balanceAtDateDebit": "", 
"balanceAtDateCredit": "", 
"dateFilter": "2022-04-24" 


), 
CRUD Steps 


This is a report results data. There are no steps to take. It relies on transactional data. 


Bound Actions 


No bound actions. 
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e accounts (page 38) 


No notable changes. 
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PART 3: SALES 


In this Part, we will cover the various Sales related endpoints in Business Central. 


If you need to understand the document flow, status fields, or to customize the Sales 
Document endpoints, it is strongly recommended to read Part 8: Chapter 88: Sales & Purchase 
Documents (page 506). 
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Chapter 20: Aged Accounts Receivables 


The Aged Accounts Receivable endpoint allows you to get the data that comprises the 
Aged Accounts Receivable report. 


Primary Key 


customerld The generated identifier for the Customer is created and used under the 
hood by Business Central to uniquely identify this Customer. The field 
is a GUID. It is locked and managed by BC. 


Field Map 


API JSON: 
{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /agedAccountsReceivables/S$ent 
ate " 


"Qodata.etag": "W/N"JzE5OzQ5Mjk4OTOxNDEANzIS5MTgzMDgxOzAwOyc-N"", 
"customerId": "6e15971e-df3a-edll-bbae-6045bd8e554a", 


"customerNumber": "30000", 

"name": "School of Fine Art", 
NeurrencyCodems Www 

"balanceDue": 53833.52, 
"currentAmount": O0, 

"periodlLabel": "07/28/24-08/27/24", 
"periodlAmount": 0, 

"period2Label": "06/28/24-07/28/24", 
"period2Amount": O0, 

"period3Label": "-06/28/24", 


"period3Amount": 53833.52, 
"agedAsOfDate": "2024-08-27", 
"periodLengthFilter": "30D" 


BUSINESS CENTRAL ENTITY: 
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03/12/22 02/12/22 01/12/22 
Balance . DATA . AUS . Eu 


Trey Research 2,345.63 > 938.25 625.50 0.00 
School of Fine art 33,645.10 237. 12,094.80 12,376.10 6,936.80 
Alpine Ski Mouse 2,617.50 . 2,617.50 0.00 0.00 
Relecloud 6,762.38 2,358.38 2,202.00 2,202.00 0.00 


Total (tcy) 45,370.61 17,852.55 15,203.60 
39.3% 33.5% > 


In Business Central, there are a few settings on the report Request page: 


Aged Accounts Receivable 


Printer (Handled by the browser) 


Use default values from Last used options and filters 


Options 


Aged As Of 4/11/2022 


Aging by Due Date 


Period Length 1M 


Print Amounts in LCY e ) Off 


Print Details (e ) Off 


Heading Type Date Interval 


New Page per Customer e ) Off 


You can only set two of these settings via the API endpoint: 


e Aged As Of - will control when the periods and balances are calculated, which is 
done by filtering on the agedAsOfDate. 

e Period Length - controls the date ranges that underly the Period 1, 2 and 3 ranges. 
This is done by filtering on the periodLengthFilter using the DateFilter as a string. 


Important: Even though the Currency Code is included in the dataset, all amounts are in the 
LCY, as if the Print Amounts in LCY is checked. 


Unfortunately, there are issues in the filtering on this endpoint in some regions, so you may 
have challenges using it. For more information, see Part 8: Chapter 91: API Bugs (page 517). 
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The first result in the dataset (it is sorted by Customerld, the systemld of the Customer) will 
have an Id of 00000000-0000-0000-0000-000000000000 and be the Total Row. 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /agedAccountsReceivables 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /agedAccountsReceivables (6e1597le-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /agedAccountsReceivables", 
"value": [ 


{ 
"@odata.etag": "W/N"JzIWOzE3MjM2NDUzODMyMzQ5MjO1MjI2MTswMDsnN"", 
"customerId": "00000000-0000-0000-0000-000000000000", 


"customerNumber": "", 
"name Tota 
Ucunmcemneweosdecl UU 
"balanceDue": 0, 
"currentAmount": O0, 
"periodlLabel": "", 
"periodlAmount": 0, 
Noendod2da cl muu 
"period2Amount": O0, 
"period3Label": "", 
"agedAsOfDate": "2024-08-27", 
"periodLengthFilter": "30D" 


"Qodata.etag": "W/N"JzE5OzgwMzg2NzY3NzA1MjYyMDYA4NDYxOzAwOyc-N"", 
"customerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 


"customerNumber": "10000", 

"name": "Adatum Corporation", 
Ucuncemneyeodet Wit, 

"balanceDue": 0, 

"currentAmount": O0, 

"periodlLabel": "07/28/24-08/27/24", 


"periodlAmount": O0, 
"period2Label": "06/28/24-07/28/24", 
"period2Amount": 0, 


"period3Label": "-06/28/24", 
"agedAsOfDate": "2024-08-27", 
"periodLengthFilter": "30D" 


"Qodata.etag": "W/N"JzE4OzQwMTY2MTEyMjI1MjUANTCSNjE7MDA7Jw--N"", 
"customerId": "6d15971e-df3a-edl1-bbae-6045bd8e554a", 


"customerNumber": "20000", 
"name"; "Trey Research", 
NeurrencyCode": Mi, 


"balanceDue": 3036.6, 
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"currentAmount": 0 


li 
"periodlLabel": "07/28/24-08/27/24", 
"periodlAmount": 0, 
"period2Label": "06/28/24-07/28/24", 
"period2Amount": 0, 
"period3Label": "-06/28/24", 


"period3Amount": 3036.6, 
"agedAsOfDate": "2024-08-27", 
"periodLengthFilter": "30D" 


CRUD Steps 


CREATING 


Creating and posting an Invoice for a customer will add data to this report resultset. 
However, instructions on creating and pointing invoices is beyond the scope of this book. 


Bound Actions 


No bound actions. 


e customers (page 110) 


| Version Changes 


25.0 Period Label fields were added. 
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Chapter 21: Contacts 


The Contact system is a part of the light CRM functionality within the Business Central 
system. Contacts are usually either a Company or Person type, with the Company Contacts 
having the ability to be connected to Customers, Vendors, Bank Accounts, or Employees. 
Person type contacts are associated with a Company Contact. 


This connection is used in multiple places, but one example is entering a Sales Order 
where you can choose which Contact ordered the SO from a list of associated Contacts with 
that Customer. 


This framework is how you can store different phone numbers, email addresses, and more, 
for different people within an organization. 


Contacts also allow users to enter information about prospective Customers and Vendors, 
allowing easy conversion later. 


Primary Key 
No. The identifier of the Contact. The field is 20 characters and 
alphanumeric. 


Field Map 


API JsoN: 


"Qodata.etag": "W/N"JzIwOzEA4MjI2MzMwMjk3MTEzMTY2OTA5MTswMDsnN"", 
"id": "8e3bccee-9dfc-ee11-9f8c-6045bde98c0f", 
"number": "CT000001", 


"type": "Company", 

"displayName": "Adatum Corporation", 
Topti tket dude 

"companyNumber": "CT000001", 
"companyName": "Adatum Corporation", 
"contactBusinessRelation": "Customer", 
"addressLinel": "192 Market Square", 
"addressLine2": "", 


PART 3: SALES 
CHAPTER 21: CONTACTS 


rente e Netana, 

Weir eee s "GA", 

Westec yag WISI 

Ypostcalcoaet WS EM. 

"phoneNumber"; "", 

"mobilePhoneNumber": "", 

"email": "adatum.corporation@contoso.com", 
isses E Sg M 

"searchName": "ADATUM CORPORATION", 
"privacyBlocked": false, 
"taxRegistrationNumber": "", 
viadsernteractronpate mU 5-0 
"lastModifiedDateTime": "2024-04-17T09:36:51.452" 


BUSINESS CENTRAL ENTITY: 


adatum.corporation@contoso.com IQ 
Robert Townes Adatum Corporabon Customer robert. townesQ co 
Alpine Ski House Alpine Ski House Customer 
lan Deberry Alpine Ski House Customer 
CEO of Spare Brained ideas CEO of Spare Brained Ideas None 


Fabrikam, Inc. Fabrikam. Inc. Vendor 4255550101 
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t Card d 


CTO000001 - Adatum Corporation 


[5 

EZ 

=) 
] 


a 


Report 


General 


9/23/2022 1:29 AM 


lastinteractionDate 


companyNumber Attemptec 5/1/2022 


companyName 
contactBusinessRelation Segment 
searchName Privacy Blocke o privacyBlocked 


History Manage Functions 


nterachon 


> Sales Statement - by Jim Olive : JQ Statement 
Coversheet - by Jim Olive J Coversheet 
Sales Order Confirmation - by J Order S-ORD101002 


Sales Order Confirmation - by J Order S-ORD101001 
Communication 


Address Contact 


addressLine2 Mobile Phone No mobilePhoneNumber 
| ^ email — Pm 


Show Map 


Foreign Trade 


Note that the taxRegistrationNumber may vary in which field it is connected to, 
depending on which Localizations the Business Central system has enabled. 
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GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/contacts 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/contacts (d1572523-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 


{ 


"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({{companyID}})/contacts", 
"value": [ 


{ 
"@odata.etag": "W/N"JzIwWOzE4MjI2MzMwMjk3MTEzMTY2OTAS5MTswMDsnN"", 
"id": "8e3bccee-9dfc-eell-9f8c-6045bde98cO0f", 
"n mb est eed 
Iitivao eum omp'ernydies 
"displayName": "Adatum Corporation", 
TODT Te JU 
"companyNumber": "CT000001", 
"companyName": "Adatum Corporation", 
"contactBusinessRelation": "Customer", 
"addressLinel": "192 Market Square", 
"addressLine2": "", 
iret te a Aplantat, 
“state: MAT 
Weary S. WOES. 
JeyoxeuERUl(CoxelsUs WS TEM 
"phoneNumber":; "", 
"mobilePhoneNumber": "", 
"email": "adatum.corporation(8contoso.com", 
"yepsite”: UU 
"searchName": "ADATUM CORPORATION", 
"privacyBlocked": false, 
"taxRegistrationNumber": "", 
"lastInteractionDate": "2024-05-01", 
"lastModifiedDateTime": "2024-04-17T09:36:51.452" 


"Qodata.etag": "W/N"JzE5OzMAMzczNTI2NjEzNjMyOTkzNDQxOzAwOyc-N"", 
"id": "8f3bccee-9dfc-eell-9f8c-6045bde98cO0f", 
"number": "CT000002", 


Ite E Personi 

"displayName": "Robert Townes", 

Joe Htaliedl e B DT 

"companyNumber": "CT000001", 
"companyName": "Adatum Corporation", 
"contactBusinessRelation": "Customer", 
"addressLinel": "192 Market Square", 
"addressLine2": "", 

lesen MEO ATI FT OP 

voraces: "GA", 

Weouiciay B. WOES. 

Jheroxeneeul(elexelsu s WS T EM. 

"phoneNumber":; "", 
"mobilePhoneNumber": "", 

"email": "robert.townes8contoso.com", ) 
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"websitet: uw 


"searchName": "ROBERT TOWNES", 

"privacyBlocked": false, 

"taxRegistrationNumber": "", 

WISE liMeSeeCee MDE S 20:9 —()1 —(0 1. 
"lastModifiedDateTime": "2024-04-17T09:37:14.7432" 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/contacts 


Example POST Request Body: 


“number : MSBT202207 

"displayName": "Spare Brained Ideas", 
"addressLinel": "Unknownl", 
"addressLine2": "Unknown2", 

Nene Goth emi ug 

"state": "Vastra Gotaland", 

country SI 

Mpostali€odew: ul sao 

"phoneNumber": "0701234567", 
"mobilePhoneNumber": "0709876543", 
"email": "noreply@sparebrained.com", 
"website": "sparebrained.com", 
"searchName": "This Is Also Editable", 
"taxRegistrationNumber": "SE550000000001" 


Example POST Response: 


{ 
"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({{companyID}})/contacts/S$entity", 
"Qodata.etag": "W/N"JzE5OzgzNDgOMDQ5MzAANTMyODE1MjUxOzAwOyc-N"", 
wow “yd5il2 559-802 eis 946 d62465245/0/6/ 
Vnumber' "SBT2022N 
"type Ws "Company" ; 
"displayName": "Spare Brained Ideas", 
Jy eost we DUMP 
"companyNumber": "SBI2022", 
"companyName": "Spare Brained Ideas", 
"contactBusinessRelation": "None", 
"addressLinel": "Unknownl", 
"addressLine2": "Unknown2", 
Ukeohiey 3 tU 5 etehemito usse 
state”. yasirasGoitadlamc", 
Vig@inieieyA es Sys 
Isso pieculGeyeles ATASS 
"phoneNumber": "0701234567", 
"mobilePhoneNumber": "0709876543", 
"email": "noreply@sparebrained.com", 
"website": "sparebrained.com", 
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"searchName": "THIS IS ALSO EDITABLE", 
"privacyBlocked": false, 
"taxRegistrationNumber": "SE550000000001", 


"lastInteractionDate": 


"lastModifiedDateTime": 


MOOOL=O L091", 
TZOZ4 OOO 4001 1e AS e265 svat 


PATCH 


Example PATCH Request 


URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/contacts (7d5125b9-8d21-ef11-9467-d62465a5064f) 


Example PATCH Request 


Body: 


"companyName": "SBI", 


"searchName": "SPARE B 


Wlosniiees Wariga, / IS 


RAINED IDEAS", 
arebrained.com" 


Example PATCH Response: 


{ 
Vidodatancontextw: UMEE 

23cu5:7048/BC/api/v2.0/Sme 
"Qodata.etag": "W/N"Jz 
Wichs Wiel il 2S)? as 
Waiter Wistar Za 5 
Wego es E Company ty 
"displayName": "Spare 
Moorelle: m 
"companyNumber": "SBI2 
"companyName": "SBI", 
"contactBusinessRelati 
"addressLinel": "Unkno 
"addressLine2": "Unkno 
Iesv UG Ot mMeniouncg Ley 
strated gs "esee Gota 
Weenies SI 
Jheroxenesullelexeleng Walz S 
"phoneNumber": "070123 
"mobilePhoneNumber": " 
"email": "noreply8spar 
Ivens iret m m EDS SI 
"searchName": "SPARE B 


p://demo- 

tadata#companies ({{companyID}}) /contacts/Sentity", 
E5OzgzNDgOMDQ5MzAANTMyODE1MjUxOzAwOyc-N"", 

fu Wo cioediobabioóA f 


Brained Ideas", 
O22" 5 


One ENONSA, 
inal 
wn2", 


andi 


AMSG TM 
0709876543", 
ebrained.com", 
arebrained.com", 
RAINED IDEAS", 


"privacyBlocked": false, 


"taxRegistrationNumber 
"lastInteractionDate": 
"lastModifiedDateTime" 


"; "SE550000000001", 
NOOOL-Ol S01, 
5 UZA0 24 Oe Os Seas AGO), Zeal 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]))/contacts (7d512559-8d21-ef11-9467-d62465a5064£) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


In the Contacts list, click on the New button in the Action Bar: 


Contacts 


JO Search + New Manage Home Contact More options 


Contact 

Business 
No. Name f Company Name f Relation 
CT000001 :  Adatum Corporation Adatum. Corporation Customer 
CT000002 Robert Townes Adatum Corporation Customer 
CT000007 Alpine Ski House Alpine Ski House Customer 


CTO000008 lan Deberry Alpine Ski House Customer 


This will open a blank Contact Card. Click on the Name field (which should automatically 
assign a Contact No. - if not, enter a Contact No. manually) and enter text: 
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Contact Card v Saved 


CR000025 - Test Contact 


Home Contact Report | More options 


General 


No. CR000025 see Company No. CRO00025 


Test Contact see Company Name 


Company Business Relation 


Salesperson Code 


UPDATING 


Open a Contact Card from the Contacts list and adjust the Name field. 


DELETING 


Select the Manage button in the Action Bar from the Contacts list and choose the Delete 
action. 


Bound Actions 


No bound actions. 


e contactlnformation (page 105) — it is technically possible to call this API from this 
context, but you must provide filters to complete the call. If you have the values 
needed for the filters, you have the information this endpoint would give you. 

e countryRegion (page 402) - this should return the Country/Region of the contact. 
However, does not - it returns an error. (See Part 8: Chapter 91: API Bugs on page 
517.) 

e picture (page 453) 


Changes 
Field Added: jobTitle 


The Business Relation (businessRelation) field was obseleted and will be 
replaced by the Contact Business Relation (contactBusinessRelation). 
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Chapter 22: Contact Information 


The Contact Information endpoint is designed to get all the Contacts associated with a 
given Customer, Vendor, Bank Account or Employee. 


To call this endpoint, you need to supply two filters in the URI: 


e relatedType - this should be a string of any of the following: 
o Customer 
o Vendor 
o Bank Account 
o Employee 
e relatedid - the systemld of the entity you want the connected Contacts for 


Primary Key 


Contact Id The generated identifier systemld of a related Contact. 


Field Map 


API JSON: 
{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /contactsInformation", 
"value": [ 
{ 
"Qodata.etag": "W/\"JzIwOzE20DMyMzUwMTOZNTM2MTMzOTY yMTswMDsn\"", 
"contactId": "d1572523-df3a-edll-bbae-6045bd8e554a", 
"contactNumber": "CT000001", 
"contactName": "Adatum Corporation", 
"contactType": "Company", 
"relatedId": "6c15971e-df3a-edll-bbae-6045bd8e554a", 
"relatedType": "Customer" 
), 
{ 
"Qodata.etag": "W/\"JzIwOzE20DIwMDAxMDQ3MDUyNTYOMjYxMTswMDsn\"", 
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"contactId"; "d2572523-df3a-ed11-bbae-6045bd8e554a", 


"contactNumber": "CT000002", 

"contactName": "Robert Townes", 

Neoneacel ype! “Person, 

"relatedId": "6c15971e-df3a-edll-bbae-6045bd8e554a", 
"relatedType": "Customer" 


BUSINESS CENTRAL ENTITY: 


This entity does not have a directly clear page, but it is based on two parts: 


e Company connection to Business Central entities (Business Relations) 
e Person Contacts to the Company Contact (Related Contacts) 


Depending on the version of Business Central, you may have the ability to drill-down to 
the following setup from the main Contact Card itself. However, the following steps are 
universally correct: 


From the Company type Contact card, you can see the connection via the Action Bar, in 
the Related, Contact, Company, Business Relations: 


Contact Card 


CROOO025 - Test Contact 


Home Contact Report Actions Related Automate Fewer options 


I3 Contact ? B Company Zi, Business Relations 
General 


&$ Related Information & Person E] Industry Groups 
CR000025 i 
———— fy] Tasks EE Alternative Address ® Web Sources 
Test Contact ontact 
7 © History Other 
Companv V Business Relation 


This will show a list of the connections: 
Contact Business Relations 


p Search + New EZ Edit List li] Delete E=] Open Card Page More options 


Business 
Relation Code f Business Relation Description Link to Table : Name 


CUST v | * Customer Customer Adatum Corporation 
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From the Contact Card, you can also see the Related Contacts via Related, Related 


Information, Related Contacts: 


Contact Card "A e 


CT000001 - Adatum Corporation 


Home Contact Report Actions ~ Related ~ 


§ Contact 
General 


&$ Related Information 


CT000001 n 
[7] Tasks 


Automate ~ 


Fewer options 


E Mailing Groups 


00001 
g Online Map 


Adatum Corporatic i A T 
© History á Other &* Related Contacts 
Business Kelation cus 
2s Segments 
Salesperson Code JO 


Company 


9 rice 


Which will show a list of all the Contacts associated with this Contact: 


CT000001 - Adatum Corporation 


Contacts Ø Search + New Manage Home Contact More options 


Contact 
Business 


No. Name f Company Name f Relation 


Phone No. Email 


CT000001 Adatum Corporation Customer 


Adatum Corporation 


adatum.corporationG con 


CT000002 Robert Townes Adatum Corporation Customer robert.townes@contoso.c 


GET 


Example GET Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/contactsInformation?$filter=relatedType eq 'Customer' and 
relatedId eq 6c15971e-df3a-edll-bbae-6045bd8e554a 


Example GET Response: 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({ {companyID}})/contactsInformation", 
"Xalue": [ 


{ 


"Qodata.etag": "W/N"JzIwWOzE2ODMyMzUwWMTOzNTM2MTMzOTY yMTswMDsnN"", 
"contactId": "d1572523-df3a-ed1l1-bbae-6045bd8e554a", 


"contactNumber": "CT000001", 

"contactName": "Adatum Corporation", 

Neconvactlype™: "Company, 

"relatedId": "6c15971e-df3a-edll-bbae-6045bd8e554a", 
"relatedType": "Customer" 


"Qodata.etag": "W/N"JzIWOzE2ODIwMDAxMDQ3MDUyNTYOMjYxMTswMDsnN"" 
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"contactId"; "d2572523-df3a-ed11-bbae-6045bd8e554a", 


"contactNumber": "CT000002", 

"contactName": "Robert Townes", 

Neontactlype” = “Person, 

"relatedId": "6c15971e-df3a-ed1l1-bbae-6045bd8e554a", 
"relatedType": "Customer" 


CRUD Steps 


CREATING 


Follow the steps in the Contact endpoint to create a new Contact. With that new Contact, 
you can create a new Customer, which will connect the Contact to the new Customer, creating 
the link. From that Contact Card, in the Action bar, select Action, Functions, Create As, 
Customer: 


Contact Card 


CT000001 - Adatum Corporation 


Home Contact Report Actions w Related Automate ~ Fewer options 


f Functions > & Launch Web Source 
General 


CE Apply Word Template Eà, Print Cover Sheet 
No. CTOO ary] ES 
Other Create as >  & Customer 
Adatum corporation 
- [gl Link with existing >  & Vendor 
Company 
C Analyze Picture fü Bank 


Depending on the Business Central configuration, it should ask which template should be 
applied, as follows: 


Select a template for a new customer | ® v 


Code f Description Contact Type Y 


> CUSTOMER COMPANY : Business-to-Business Customer (Bank) Company 
CUSTOMER EU COMPANY EU Customer (Bank) Company 


Once one is selected, a Customer will be created, and the Contact will now have a Business 
Relation to it. 


UPDATING 


PART 3: SALES 
CHAPTER 22: CONTACT INFORMATION 


You can re-assign the Contact to a different Business Relation via the Contact Related 
Information screen: 


Contact Business Relations 


2 Search + New E? Edit List lil] Delete E=] Open Card Page More options 


Business 
Relation Code t Business Relation Description Link to Table No. Name 


> CUST : Customer Customer C00020 v | Test Contact 


No. T Name 
30000 School of Fine Art 


40000 Alpine Ski House 
50000 Relecloud 
C00010 Something 
C00020 Test Contact 


DELETING 


Via the Contact Business Relations, you can also delete the connection. 


Bound Actions 


No bound actions. 


Navigations 


e contacts (page 97) 
e customers (page 110) 
e vendors (page 291) 


No notable changes. 
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Chapter 23: Customers 


The Customer endpoint gives access to the Customers in Business Central. 


Primary Key 


No. The identifier of the Customer. The field is 20 characters and 
alphanumeric. 


Field Map 


API JsoN: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/customers/Sentity", 
"Qodata.etag": "W/\"JzE50zE5MjYONjJEZMjYONTO2NTY OMDAxOzAwOyc=\"", 
"id": "6c15971e-df3a-edll1-bbae-6045bd8e554a", 
"number": "10000", 
"displayName": "Adatum Corporation", 
"type" : "Company" 7 
"addressLinel": "192 Market Square", 
"addresshuine2zWo lm" 
Westies, Ute Ieee 
"staten: TGAN 
Jexenpbouras WA B. UOS 
“posca loden wos TRU 
"phoneNumber":; "", 
"email": "robert.townes@contoso.com", 
Wiles 9 uar 
"salespersonCode": "JO", 
"balanceDue": 0, 
caecus: Lumines. Ol, 
"taxLiable": true, 
"LtaxAreald": "46572523-df3a-edll-bbae-6045bd8e554a", 
"taxAreaDisplayName": "ATLANTA, GA", 
"taxRegistrationNumber": "", 
"currencyId": "00000000-0000-0000-0000-000000000000", 
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Vewmnencyicocde! i TUSD 

"paymentTermsId": "7b14971e-df3a-ed11-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"paymentMethodId": "00000000-0000-0000-0000-000000000000", 
plockedii u00 0). 0 

WlastModaiiedDakelimen: A7022 -—09-—23 Ot 29 ao 6/09/97) 


BUSINESS CENTRAL ENTITY: 


New Document Prices & Discounts 


Robert Townes 
Trey Research Helen Ray 
School of Fine Art Meagan Bond 
Alpine Sid House lan Deberry 


Relecioud Jesse Homer 


10000 - Adatum Corporation 


number , salespersonCode 


displayName 


balanceDue 


blocked Modified lastModifiedDateTime 


Address & Contact 


creditLimit 0.00 fit 37 
Address 


addressLine2 nN 
country Home Pag 
city (qua j ENU 
state 
postalCode 


phoneNumber 


The Tax Related fields vary based on localizations. For example, this is the Invoicing 
FastTab for some Europe-localized versions: 
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Invoicing 


Bill-to Customer v Prices and Discounts 

VAT Registration No Currency Code 
EORI Number Customer Price Group 

GLN Customer Disc. Group 

Use GLN in Electronic D e» Off Allow Line Disc 

Copy Sell-to Addr. to Q Company Invoice Disc. Code 
Posting Details Prices Including VAT 
Gen. Bus. Posting Group DOMESTIC 


VAT Bus. Posting Group taxAreaId 


Customer Posting Group DOMESTIC 


Whereas, this is the Invoicing FastTab in the US-localized version: 


Invoicing 


Posting Details 


taxRegistrationNumber Gen. E ting Group DOMESTIC 


DOMESTIC 


d 


z Currency Cod currencyCode 
company 


«D taxLiable 
taxAreald 


Legal Entity 
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Payments Show less 


Prepayment 96 Cash Flow Payment Ter... 


Application Method Print Statements «D 


Partner Type Last Statement No. 


Intrastat Partner Type Block Payment Tolerance 9 


Payment Terms Code paymentTermsId Preferred Bank Account... 
Payment Method Code paymentMethodId Bank Communication E English 


Reminder Terms Code Check Date Format 


Fin. Charge Terms Code Check Date Separator 


Shipping Show more 


Ship-to Code Shipping Advice Partial 

Location Code Shipment Method 

Combine Shipments o Code 
Reserve Optional Base Calendar Code 


Customized Calendar 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/customers 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/customers (6c1597le-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/$metadatafcompanies (((companyID]])/customers", 
"value": [ 
1 


"@odata.etag": "W/N"JzESOzE5MjYONjEzMjYONTO2NTYOMDAxOzAwOyc-N"", 
"id": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 


mmumoer u UE) Y0)0) 

"displayName": "Adatum Corporation", 
"type": "Company", 

"addressLinel": "192 Market Square", 
"addressLine2": "", 

Jesbeg V E Ware lle 

"atate "GA", 
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eoume eyan MOS 

upostalcodet i sul te 

"phoneNumber": "", 

"email": "robert.townes@contoso.com", 

"website": UE 

"salespersonCode": "JO", 

"balanceDue": 0, 

ese cite momies m 

"taxLiable": true, 

"taxArealId": "46572523-df3a-edll-bbae-6045bd8e554a", 


"taxAreaDisplayName": "ATLANTA, GA", 
"taxRegistrationNumber": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
Necurrency€ode: “US DIT, 


"paymentTermsId": "7b14971e-df3a-ed1l1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"paymentMethodId": "00000000-0000-0000-0000-000000000000", 
silos gs UU xOC20_ Uo 

"lastModifiedDateTime": "2024-05-14T01:29:55.6832" 


"Qodata.etag": "W/\"JzE50zM1MjM50DgzNDc5MzA3MjMyNDgxOzAwOyc=\"", 
"id": "6d15971e-df3a-edll1-bbae-6045bd8e554a", 
"number": "20000", 


"displayName": "Trey Research", 
"type" : "Company" 7 

"addressLinel": "153 Thomas Drive", 
"addressLine2": "", 

Weni  Welsketeieie p 

Weir alice e WET Vig 

Weronsbaiciaye WOKS 

Uisorsieculiciycle vs GP 
"phoneNumber":; "", 

"email": "helen.ray@contoso.com", 
Iesse uu 

"salespersonCode": "JO", 


"balanceDue": 3036.6, 

Heredi enir mi E0 

"taxLiable": true, 

"taxAreald": "47572523-df3a-edll-bbae-6045bd8e554a", 


"taxAreaDisplayName": "CHICAGO, IL", 
"taxRegistrationNumber": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"cun 5enceyeodeV i RUSDA 


"paymentTermsId": "7914971e-df3a-edll1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"paymentMethodId": "00000000-0000-0000-0000-000000000000", 
"isUbexedssiohg: VW xOOZ0 A 
"lastModifiedDateTime": "2024-05-14T01:29:55.6972" 

), 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]])/customers 


Example POST Request Body: 


"displayName": "CEO of Spare Brained Ideas" 


PART 3: SALES 
CHAPTER 23: CUSTOMERS 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/customers/Sentity", 
"Qodata.etag": "W/N"JzE5OzOzOTEwODI3NjESOTMIMDQwMDYxOzAwOyc-N"", 
Wid": w8429df9a-4T154—ed11—946£f-000d3a8dc6561' 

"number": "C00010", 

"displayName": "CEO of Spare Brained Ideas", 
itv cM Dems onp 

"addressLinel": "", 

"addressLine2": "", 

SEREY: "W s 

Totato S WM 

"erensbouese wg. WOES 

"posudlleodcom mu 

"phoneNumber"; "", 

"emails un 

"website": "", 

"salespersonCode": "", 

"balanceDue": 0, 

cec amd 

"taxLiable": true, 

"taxAreaId": "00000000-0000-0000-0000-000000000000", 


"taxAreaDisplayName": "", 
"taxRegistrationNumber" : woe ; 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"currencyCode" : "USD" ; 


"paymentTermsId": "8214971e-df3a-edll1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"paymentMethodId": "ee562523-df3a-edll-bbae-6045bd8e554a", 
Wisloeleclg W eoe) wr 

"lastModifiedDateTime": "2024-06-03T10:32:57.352" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/customers(8429df9a-4154-ed11-946£-000d3a8dc661) 


Example PATCH Request Body: 


mum Sie is 9g 
"email": "noreply@sparebrained.com", 
"website": "https://sparebrained.com" 


Example PATCH Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 

/APIBook/api/v2.0/$metadatafcompanies ({{companyID}})/customers/Sentity", 
"Qodata.etag": "W/N"JzIWOzE1MDQONzcS5NzExNTg2NDMyMjMOMTswMDsnN"", 
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"id"; "8429df9a-4154-ed11-946f-000d3a8dc661", 


Jisyepntexess Ug: MAYO LU. 

"displayName": "CEO of Spare Brained Ideas", 
Utewore a Wieieiesyoug 

"addressLinel": "", 

"addressLine2": "", 

Wigan tanya: Hr 

Weimer. pu 

Sconti ya URS. 

PHoswali€ode m Unu 

"phoneNumber":; "", 

"email": "noreply@sparebrained.com", 
"website": "https://sparebrained.com", 
"salespersonCode"; "", 


"balanceDue": 0, 

Wee Guinean Ol 

"taxLiable": true, 

"taxAreaId": "00000000-0000-0000-0000-000000000000", 


"taxAreaDisplayName": "", 
"taxRegistrationNumber"; "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"currencyCode" : "USD" r 


"paymentTermsId": "8214971e-df3a-ed11-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"paymentMethodId": "ee562523-df3a-edl1-bbae-6045bd8e554a", 
"JsuleyelissxelUg. D OC 20 4, 

"lastModifiedDateTime": "2024-06-03T10:34:35.6832" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/customers(8429df9a-4154-ed11-946£-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


In the Customers list, click on the New button in the Action Bar: 
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Customers: All v P Search + New [i] Delete Process v Ps 2 Y 


Responsibility 
Name Center Location Code Phone No. Contact 


Adatum Corporation Robert Townes 
Trey Research Helen Ray 
School of Fine Art Meagan Bond 
Alpine Ski House lan Deberry 


Relecloud Jesse Homer 


This will open a blank Customer Card (depending on the system settings, you may have 
to select a Customer Template). Click on the Name field (which should automatically assign a 
Customer No. - if not, enter a Customer No. manually) and enter text: 


Customer Card e 


C00010 - Test Customer 


Home Request Approval New Document Prices & Discounts Customer Report 


General Show more 


No. C00010 see Credit Limit (LCY) 


Name Test Customer Blocked 


Balance (LCY) Total Sales 
Balance (LCY) As Ve... Costs (LCY) 


Balance Due (LCY) 


UPDATING 


Open a Customer Card from the Customer list and adjust the Name field. 


DELETING 


Select the Manage button in the Action Bar from the Customers list and choose the 
Delete action. 


Bound Actions 


No bound actions. 
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The Customer endpoint has many Navigation elements that allow you to fetch related 
endpoints with a built-in linkage to the Customer context. This means that if you ask for the 
agedAccountsReceivable endpoint to be expanded, you will get the content of the Aged 
Accounts Receivable endpoint specific as a subitem for the Customer entity. 


agedAccountsReceivables (page 93) 

contactsInformation (page 105) 

countryRegion (page 402) - this should return the Country/Region of the contact, 
but does not - it returns an error. (See Part 8: Chapter 91: API Bugs on page 517.) 
currencies (page 407) 

customerFinancialDetails (page 123) 

defaultDimensions (page 417) 

paymentMethods (page 440) 

paymentTerms (page 445) 

picture (page 453) 

shipmentMethods (page 457) 


Changes 
Added lastModifiedDateTime. 


Several fields were added: 
e salespersonCode 


e  balanceDue 
e creditLimit 


Additional localization handling was put in place for taxRegistrationNo 


The contactsInformation navigation was added 
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Chapter 24: Customer Contacts 


The Customer Contacts endpoint is very similar to the Contact Information endpoint 
with a few notable exceptions. 


e The endpoint is naturally defaulted to the Customer Contacts (type person), and 
there is no need to include a filter. 

e It allows for a GET, PATCH and DELETE operation, but not a POST. So you are not 
able to insert new records, but can modify or delete them. 


Primary Key 


Contact Id The generated identifier systemld of a related Contact. 


Field Map 


API JSON: 
{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/customerContact", 

"value": [ 


{ 
"@odata.etag": "W/N"JzIWOzE3NTUSMDOxMzEONDYOMzkxNDcyMTswMDsnN"", 
UTERE Gels 7310 oA Serr il See SOA Sloe) one 
"email": "robert.townes@contoso.com", 
ufirstName: SG ed 
"lastName": "Townes", 
Nosotessdonealigsiet Eu 
"customerId": "0ad39873-0764-ef11-a676-6045bdac97bf", 
"customerName": "Adatum Corporation", 
"primaryPhoneNumber":; "" 


"Qodata.etag": "W/N"JzE5OzM3OTA4MDgxOTk1MzA2NzcONjExOzAwOyc-N"", 
"id": "11d39873-0764-ef11-a676-6045bdac97bf", 


"email": "helen.ray@contoso.com", 
"firstName": "Helen", 
"lastName": "Ray", ) 
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WerOres Ss TOMalMeint ena nu 

"customerId": "0ed39873-0764-ef11-a676-6045bdac97bf", 
"customerName": "Trey Research", 
"primaryPhoneNumber":; "" 


BUSINESS CENTRAL ENTITY: 


This is the same entity as described above in the Contact Information section. 


GET 


Example GET Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 


nies ({companyID}})/customerContacts 


Example GET Response: 


{ 


"@odata.context": 


/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/customerContacts", 
"value": [ 


{ 


"Qodata.etag": "W/\"JzIwOzE3NTU5MDOxMzEONDYOMzkxNDcyMTswMDsn\"", 


Mids Odds 93ers OEA er E aE COA pda cS nDe u 
"email": "robert.townes@contoso.com", 

"firstName": "Robert", 

"lastName": "Townes", 

“profressilona Micle Gu 

"customerId": "0ad39873-0764-ef11-a676-6045bdac97bf", 
"customerName": "Adatum Corporation", 
"primaryPhoneNumber": "" 


"Qodata.etag": "W/N"JzE5OzM3OTA4MDgxOTk1MzA2NzcONjExOzAwOyc-N"", 


midt les 2873-04 esq ao76-16045063dac] 9t 


"email": "helen.ray@contoso.com", 

"firstName": "Helen", 

"lastName": "Ray", 

T professiona bit tensi nun 

"customerId": "0ed39873-0764-ef11-a676-6045bdac97bf", 
"customerName": "Trey Research", 


"primaryPhoneNumber":; "" 


"Qodata.etag": "W/N"JzE5OzQ2MDCyMTMzNzY2MDg4NjUxOTIxOzAwOyc-N"", 


Sardis dSoom9comod-eflaoyo-o045l dac 9mb fu 


"email": "meagan.bond@contoso.com", 

"firstName": "Meagan", 

IyastNamew:eUBondWu 

"protress ona Pit let Muy 

"customerId": "124d39873-0764-ef11-a676-6045bdac97bf", 
"customerName": "School of Fine Art", 


"primaryPhoneNumber":; "" 
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"https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/customerContacts (0dd39873-0764-ef11-a676-6045bdac97bf) 


Example PATCH Request Body: 


"email": "bob.townes@contoso.com" 


Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/customerContacts/Sentity", 

"@odata.etag": "W/N"JzIWOzE3MDkOOTAwMDC2OTE2NjcyNzgzMTswMDsnN"", 

"id": "0dd39873-0764-ef11-a676-6045bdac97bf", 

"email": "bob.townes@contoso.com", 

"firstName": "Robert", 

"lastName": "Townes", 

“professiona Cit leis) wu 

"customerId": "0ad39873-0764-ef11-a676-6045bdac97bf", 

"customerName": "Adatum Corporation", 

"primaryPhoneNumber": "" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerContact (0dd39873-0764-ef11-a676-6045bdac97bf) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content”. However, there are several checks when deleting contacts that might be 
returned if Business Central's validation logic returns an error. 


CRUD Steps 


This is the same process as Contact Information earlier in this chapter. 
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Bound Actions 


No bound actions. 


Navigations 


e contacts (page 97) 
e customers (page 110) 


History 


| Version Changes 


25.0 Added 
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Chapter 25: Customer Financial Details 


The Customer Financial Details endpoint gives a little extra information about the 
Customer's financials beyond the Customer endpoint. 


While the Customers endpoint gives only the Balance Due, this endpoint additionally 
gives Balance (to date) and Sales (to date). 


Primary Key 
No. The identifier of the Customer. The field is 20 characters and 
alphanumeric. 


Field Map 


API JSON: 
{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/$metadatascompanies(((companyID)])/customerFinancialDetails/$en 
(pati Pr 


"Qodata.etag": "W/N"JzE5OzQ2MzMANTMxNjU3NTIyODczNjkxOzAwOyc-N"", 
"id": "6c15971e-df3a-edl1l-bbae-6045bd8e554a", 

V rumes n: 

Noalancel 0, 

"tobalsalesExclucdiümngTrasi: 22959994 

"overdueAmount": 0, 

"lastModifiedDateTime": "2024-04-17T09:36:58.9032" 


BUSINESS CENTRAL ENTITY: 
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ard 


10000 - Adatum Corporation 


Process Request Approval New Document Prices & Discounts Customer Report 


General 


number 


Adatum Corporation 


00 otal Sak totalSalesExcludingTax 
t 40255.70 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerFinancialDetails 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/customerFinancialDetails (842 9df9a-4154-ed11-946f-000d3a8dc661) 


Example GET Response (entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/S$metadata#companies ({ {companyID}})/customerFinancialDetails", 
"value": [ 


{ 
"Qodata.etag": "W/N"JzE5OzQO2MzMANTMxNjUS3NTIyODCzNjkxOzAwOyc-N"", 


"id": "6c15971e-df3a-edl1-bbae-6045bd8e554a", 
“number lOO OOM, 

"balance": 0, 

"tobalsadesixclucdiungTras'tu229599 
"overdueAmount": O0, 

“lastModifiedDaterime™: "2024-—04-—31:7/70)/:3/6:58:9032!' 


"@odata.etag": "W/N"JzE5OzQ2MzMINZzUyMjA3ODUyNTk2NTAxOzAwOyc-N"", 
"id": "6d15971e-df3a-edl1l-bbae-6045bd8e554a", 
"number": "20000", 
"balance": 3036.6, 
“totalSalicshxe ludingLax!:) 586737 
"overdueAmount": 3036.6, 
"lastModifiedDateTime": "2024-04-17T09:36:58.9222" 
Ie 


CRUD Steps 


This is a read-only endpoint which exposes the results of a report. No actions in Business 
Central are possible to directly change the data that will be displayed in this report. 
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Bound Actions 


No bound actions. 


Navigations 


e customers (page 110) 


History 


| Version Changes 


23.0 Added lastModifiedDateTime. 


PART 3: SALES 
CHAPTER 25: CUSTOMER FINANCIAL DETAILS 


Chapter 26: Customer Payment Journals 


Despite the name, this endpoint exposes the Cash Receipts Journal batches. One of the 
large areas of confusion is mixing terminology for this endpoint. It is not to be confused with 
the following: 

e Receive Payments, Register Payments, Payment Registration — these are all 
simplified methods of receiving payments from customers but are separate from 


the Cash Receipts Journal. 
e Payment Journals - this journal is for making payments to Vendors. 


Functionally, this endpoint works like the General Journal endpoint, with a hierarchy of 
the following: 


e Journal Template 
o Journal Batch 
= Journal Line 


We access the Journal Batches for the Cash Receipt Journals in this endpoint. 


For non-Business Central people, Journal Batches are worksheets of Journal Lines. The 
structure is along the following lines: 


Journal 


eControls Pages/Reports used 


Template 


Journal *Allows Multiple sets of 
users to work with 


Batch journal lines 


Journal 
Lines 


Journal Templates allow users to post different types of journals, such as payments made 
out, cash receipts, etc. 


Functionally, Journal Batches are similar to Excel worksheets, just a means of keeping 
records separate and posting them separately. 
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This endpoint allows you access to this Journal Batch list and related records. 


Important note: Journal Template Filter 


Unlike the General Journals, which received an update to allow filtering/control of the 
Journal Template involved, this endpoint only works in the original, forced-filter method: 


This endpoint has a built-in filtering logic. Because the Journal Batch is a subset of Journal 
Templates, the system must either ask you for a Journal Template to use or have a means built- 
in to decide. 


The current method Business Central uses is to decide which Journal Template to use for 
you. It does so by the following: 


e Of all the General Journal Templates (non-Recurring). 
e That are of Type Cash Receipt. 
e Whichever is first (alphabetically). 


This means if your Business Central company has multiple Journal Templates like the 
example here: 


General Journal Templates 


2 Search +New BE Edit List [i] Delete Related Fewer options 


Bal. Account Bal. Account 
Name Î Description Type ts Type No. No. Series 


ASSETS Fixed Asset G/L Journal Assets G/L Account FA-JNL 
BNKDEPOSIT Bank Deposit Journals Bank Depo... Bank Accou... 

CASHRCPT Cash receipts Cash Recei... G/L Account GJNL-RCPT 
GENERAL GENERAL General G/L Account GJNL-GEN 
IC-DEPOSIT : Interco - Cash Receipt Cash Recei... G/L Account GJNL-RCPT 


INTFRCOMP Intercompanv Intercomna... G/l Account IC GINI 


You can see there are two Templates, CASHRCPT and IC-DEPOSIT defined as Type of Cash 
Receipts. All calls to the Journal endpoint will use the Journal Batches defined only for the 
Template CASHRCPT. The IC-DEPOSIT batch will be inaccessible. 


Primary Key 


Journal Template Name | The name of the Journal Template. The field is 10 characters and 
alphanumeric. 
Name The name of the Journal Batch. The field is 10 characters and 
alphanumeric. 
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Field Map 


API JSON: 


{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({ {companyID}}) /customerPaymentJournals/Sent 
abies 4 

"@odata.etag": "W/N"JzIwOzEyNzYyNTgyODMzMzExMDQ2Mzc1MTswMDsnN"", 

"id": "2e5a2523-df3a-edl1l-bbae-6045bd8e554a", 

codon MR BEAT 

"displayName": "GENERAL", 

"lastModifiedDateTime": "2024-04-17T09:36:57.4572", 

"balancingAccountId": "00000000-0000-0000-0000-000000000000", 

"balancingAccountNumber": "10100" 


BUSINESS CENTRAL ENTITY: 


CASHRCPT Cash receipts 


General Journal Bg | + New B? Edit List (a) Bj Post v 


Posting No. 
Name 1 Description Bal. Account Type No. No. Series Series Reason Code 


> GENERAL : | GENERAL G/L Account 10100 GJNL-RCPT 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerPaymentJournals 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerPaymentJournals (2e5a2523-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (1 entity shown): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/customerPaymentJournals", 
"value": [ 


{ 
"@odata.etag": "W/N"JzIwOzEyNzYyNTgyODMzMzExMDQ2Mzc1MTswMDsnN"", 
"id": "2e5a2523-df3a-edll-bbae-6045bd8e554a", 
codek E GENERA, 
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"displayName": "GENERAL", 


"lastModifiedDateTime": "2024-04-17T09:36:57.4572", 
"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "10100" 


} 
] 
} 
POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerPaymentJournals 


Example POST Request Body: 


"code": "PAYPAL" 


Example POST Response: 


{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /customerPaymentJournals/S$ent 
EWE 

"Qodata.etag": "W/N"JzIwOzE3MDk1MjYwMTC5ODA3NTAA4NjAzMTswMDsnN"", 

Jstgpég Wieewrelsisie-0 9d eC il ses o-UOWcSiaisiclees2 ! 

"code": "PAYPAL", 

"displayName": "", 

"lastModifiedDateTime";: "2024-06-03T10:45:55.6132", 

"balancingAccountId": "00000000-0000-0000-0000-000000000000", 

"balancingAccountNumber": "" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/customerPaymentJournals (2e6fd35f-5054-ed11-8c36-000d3a8dcc52) 


Example PATCH Request Body: 


"displayName": "PayPal Transactions" 


Example PATCH Response: 
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"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /customerPaymentJournals/S$ent 
attey s 

"Qodata.etag": "W/N"JzIWOzE3MDkOOTAwMDC2OTE2NjcyNzgzMTswMDsnN"", 

Willig WeaGieclsisit 0s EE les o-UOUcCSaviceios2 4 


"code": "PAYPAL", 
"displayName": "PayPal Transactions", 
"lastModifiedDateTime": "2024-06-03T10:47:38.132", 


"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerPaymentJournals (2e6fd35f-5054-ed11-8c36-000d3a8dcc52) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


As General Journal Batches are a subset of Journal Templates, the Journal Batches can 
be found in the General Journal Templates page, under the Action Bar's Related -> Template 
-» Batches (with the appropriate Template selected): 


General Journal Templates 


Ø Search + New Ee Edit List [i] Delete | Related ^^ Automate v Fewer options 


5] Template > Ed Batches 


Bal. Account Bal. Account 
Description Type Rec... Type No. No. Series 


ASSETS : Fixed Asset G/L Journal Assets G/L Account 
CASHRCPT Cash receipts Cash Recei... G/L Account GJNL-RCPT 
GENERAL GENERAL General G/L Account GJNL-GEN 


INITEDCTYNAD Intarcamnanu Intarcamna (2H Account IC GIN 


This opens the editable list of General Journal Batches: 
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CASHRCPT Cash receipts 


General Journal Batches Ø Search + New BE Edit List f] Delete Home [Éf Post | v + 


Bal. 
Account Posting No. 
Name f Description Bal. Account Type No. No. Series Series Reason Code 


— | GENERAL : GENERAL G/L Account 10100 GJNL-RCPT 


Click New to create a new entry and manually enter an Alphanumeric Name. 


UPDATING 


The safest and simplest method to trigger an Update of a General Journal Batches is to 
alter the Description field. 


DELETING 


General Journal Batches can be deleted. Just be aware that this will delete all related 
General Journal Lines that still need to be posted. 


Bound Actions 


No bound actions. 


Navigations 


e accounts (page 38) - this should return the account endpoint for the Bal. Account 
No. of the Batch. However, it does not work. (See Part 8:Chapter 91: API Bugs, 
page 517) 

e CustomerPayments (page 132) - the lines of the Cash Receipt Journal Batch 


No notable changes 
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Chapter 27: Customer Payments 


This endpoint is called as part of a call to the customerPaymentJournals endpoint, 
provided a journalld. 


Primary Key 


Journal Template | The name of the Journal Template. The field is 10 characters and 

Name alphanumeric. 

Journal Batch The name of the Journal Batch. The field is 10 characters and 

Name alphanumeric. 

Line No. This is a system-assigned integer. This is typically created in increments 
of 10000, so lines may be inserted between other records. 


Field Map 


API JSON: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /customerPaymentJournals (2e5a 
2523-df3a-edll-bbae-6045bd8e554a)/customerPayments", 
ava Mene 
{ 
"Qodata.etag": "W/\"JzE50zgwNjY3MjQwOTMzMzE4MTMwNTMxOzAwOyc=\"", 
Wig: Wce42beo2d—5554—ed ial —sic3 6-00 0d3asdces2y, 
"journallId": "2e5a2523-df3a-edll-bbae-6045bd8e554a", 
"journalDisplayName": "GENERAL", 
"lineNumber": 10000, 
"customerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 
"customerNumber": "10000", 
NSO ine Deca S WA0 24 .—(0 55907 
"documentNumber": "G02001", 
"externalDocumentNumber": "", 
Weimomine Ys i500), 
"appliesToInvoiceId": "00000000-0000-0000-0000-000000000000", 
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"appliesToInvoiceNumber": "", 

Ndescriperon.  “Adatum Corporacions, 

"comment": "Some Information", 
"lastModifiedDateTime": "2024-05-30T08:52:16.3072" 


BUSINESS CENTRAL ENTITY: 


Cash Receipt Journals 


Batch Name journalDisplayName 


Manage 


pe ocument No. pe Account No scriptio Amount Amount ($ 


8/22/2021 + Payment G02001 Customer 2,400.00 2400.00 G, 


Batch Name GENERAL 


Manage Home Request Approval Line More options 


Posting Date 


8/22/2021 : 2,400.00 /L Account 10100 


There are two additional fields, externalDocumentNumber and comment, that are hidden 
and must be shown via the Personalize option in the menu bar: 
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=, Environment 
E» 


APIBook 


Settings 


Dynamics 365 Business Central 
Personalize 

Design 

My Settings 

Company information 

Assisted setup 

Advanced settings 

Admin Center 


The External Document No. Field can be dragged to the page layout: 


Personalizing: General Journals + Field Clear personalization... 


General Journals Save L] ] > Add Field to Page x 


Place fields by dragging from the list to a 
position on the page. 
Batch Name DEFAULT 


p 


Manage Home pprove Request Approval Ban pplicatio Payroll =+ Bank Payment Type Ready ^ 
Date 
" x Document Date Ready 
Posting Date ype Docu t No. Type ccou Desc o o 

: Code 
4/11/2022 : TESTO1 G/L Account 10400 Accounts Receivable n NL 

External Document No. Ready 

4/11/2022 TESTO2 G/L Account 10200 Saving account 


Important: The only lines that will be visible to this API have the following: 


e Document Type: Invoice. 
e Account Type: Customer. 
e Applies-To Document Type: Invoice. 


All entries created via this API will have those fields handled directly, which means that 
you cannot do a large single payment entry and apply it to multiple documents the way you 
can within Business Central. 


GET 


Example GET Request URI Single (supplying a customerPayments Id to access a specific 
line directly): 
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https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/customerPayments (ce42b62d-5554-ed11-8c36-000d3a8dcc52) 


Example GET Response: 


1 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/$metadatadscompanies(((companyID)))/customerPayments/S$entity", 

"Qodata.etag": "W/N"JzE5OzgwNjY3MjOwOTMzMzE4MTMWNTMxOzAwOyc-N"", 

"id": "ce42b62d-5554-ed11-8c36-000d3a8dcc52", 

"journallId": "2e5a2523-df3a-edll-bbae-6045bd8e554a", 

"journalDisplayName": "GENERAL", 

"lineNumber": 10000, 

"customerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 

"customerNumber": "10000", 

tposemmgDatetk 12 072.—(0 S19) 7 

"documentNumber": "G02001", 

"externalDocumentNumber": "", 

Wamounmicss- lo OO), 

"appliesToInvoiceId": "00000000-0000-0000-0000-000000000000", 

"appliesToInvoiceNumber": "", 

ice susp tuom MAT UIne Corporations, 

"comment": "Some Information", 

"lastModifiedDateTime": "2024-05-30T08:52:16.3072" 


} 
POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerPaymentJournals (2e5a2523-df3a-ed11-bbae- 
6045bd8e554a) /customerPayments 


Example POST Request Body: 


"customerNumber": "10000", 
WHOSE line Deca S. WI (Q S 0. 
Wamoumien EOD 

"comment": "Some Information" 


Example POST Response: 


1 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies (((companyID))) /customerPaymentJournals (2e5a 
2523-df3a-edll-bbae-6045bd8e554a)/customerPayments/S$entity", 
"Qodata.etag": "W/N"JzE5OzgxNTY4ODA5NDk4Mjg4Mj YwMjAxOzAwOyc-N"", 
Wigs 3iecoe5s09—5654-edial—sic3 6-00 0dsasdees2, 
"journallId": "2e5a2523-df3a-edll-bbae-6045bd8e554a", 
"journalDisplayName": "GENERAL", 
"lineNumber": 10000, 
"customerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 
"customerNumber": "10000", 
LIV Seine Deca s W9924 —(0 5S0). 
"documentNumber": "G02002", 
"externalDocumentNumber": "", 
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amount 15007007 

"appliesToInvoiceId": "00000000-0000-0000-0000-000000000000", 
"appliesToInvoiceNumber": "", 

"description": "Adatum Corporation", 

"comment": "Some Information", 

"lastModifiedDateTime": "2024-05-30T08:56:20.492Z" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/customerPayments (3ccbc509-5654-ed11-8c36-000d3a8dcc52) 


Example PATCH Request Body: 


"customerNumber": "20000", 

JASONS ese Denes N20) vl (0 ys lb Men 
Wamounite 24010), 

"comment": "Correct Information" 


Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /customerPaymentJournals (2e5a 
2523-df3a-edll-bbae-6045bd8e554a)/customerPayments/S$entity", 

"Qodata.etag": "W/N"JzES5OzI2NTMzMzk5NjA2OTYOMDg1NDAxOzAwOyc-N"", 

Wiclig Wstexcleiol(05) 55 sd exeliL 19995-00018 Sie USIe le esa 

"journallId": "2e5a2523-df3a-edll-bbae-6045bd8e554a", 

"journalDisplayName": "GENERAL", 

"lineNumber": 10000, 

"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 

"customerNumber": "20000", 

“postingpaten MAN) Oso, 

"documentNumber": "G02002", 

"externalDocumentNumber"; "", 

"amount": 2400.00, 

"appliesToInvoiceId": "00000000-0000-0000-0000-000000000000", 

"appliesToInvoiceNumber": "", 

"description": "Trey Research", 

"comment": "Correct Information", 

"lastModifiedDateTime": "2024-05-30T08:59:30.1052" 


DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/customerPaymentJournals (2e5a2523-df3a-edll-bbae- 
6045bd8e554a) /customerPayments (3ccbc509-5654-ed11-8c36-000d3a8dcc52) 
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No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


Since Cash Receipt Lines are a journal, you open the list of Cash Receipt Journals: 


Cash Receipt Journals: — All v Jel Search —+ New lil] Delete EZ Edit List Process v 


Bal. 
Account 
Name f Description Bal. Account Type No. No. Series Posting No. Se 


GENERAL : GENERAL G/L Account 10100 GJNL-RCPT 


Clicking on the name of the batch will open the Cash Receipt Journal for editing: 


Cash Receipt Journals v/ Saved g G a" 
Batch Name GENERAL 
Manage Home Request Approval Line More options 2 Y © 
Document Account Bz 
Posting Date Type Document No Type Account No Description Amount Amount ($) Ty 
8/22/2021 * Payment G02001 Customer 20000 Trey Research 2,400.00 2,400.00 G 


At a minimum, you will need to enter the following: 


e Posting Date. 

e Document Type (of Payment). 
e Document No. 

e Account Type (Customer). 

e Account No. 

e Amount. 

e Applies-To Type (Invoice). 


You do not need to Post the entry to see it via the API. 


UPDATING 


The safest and simplest method to trigger an Update of a Cash Receipt Journal Line is 
to alter the Description field. 
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DELETING 


Cash Receipt Journal Lines can be deleted easily via the Delete action bar. 


Bound Actions 


No bound actions. 


Navigations 


e customers (page 110) 
e customerPaymentJournals (page 126) 
e dimensionSetLines (page 427) 


History 


No notable changes. 
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Chapter 28: Customer Return Reasons 


When filling out Return Orders in Business Central, one can tag a Reason Code, which 
allows for a longer descriptive text. This endpoint enables access to that description. 


Despite the name, this list of Return Reasons is also used for Purchase Return Orders for 
when Items are returned to Vendors. 


Primary Key 


Code The identifier for the Customer Return Reason. The field is 20 characters 
and alphanumeric. 


Field Map 


API JSON: 
{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /customerReturnReasons/Sentit 
y", 


"@odata.etag": "W/\"JzIwOzExMjQ2MDcwMDM4NjA5NDg5NTY5MTswMDsn\"", 
vod odsalboe oi o4—edl l= sesiG—000dsasdeea2ny, 

Veode ETUS NOPE 

"description": "Customer just said Nope and left" 


BUSINESS CENTRAL ENTITY: 
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Return Reasons 


P Search + New é Edit List [ii] Delete 


Inventory 
Description Default Location Code Value Zero 


m 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerReturnReasons 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerReturnReasons (6a8a0b3c-5754-ed11-8c36-000d3a8dcc52) 


Example GET Response (1 entity shown): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /customerReturnReasons", 
"value": [ 


{ 
"@odata.etag": "W/N"JzIwOzExMjO2MDcwMDMA4NjASNDg5NTYS5MTswMDsnN"", 
"id": "6a8a0b3c-5754-ed11-8c36-000d3a8dcc52", 
Neode UST NOPE, 
"description": "Customer just said Nope and left" 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerReturnReasons 


Example POST Request Body: 


"code" : "Just Nope", 
"description" : "Customer just said Nope and left" 


PART 3: SALES 
CHAPTER 28: CUSTOMER RETURN REASONS 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/$metadata#companies ({ {companyID}}) /customerReturnReasons/Sentit 
y", 


"@odata.etag": "W/N"JzIwOzExMjQ2MDcOMzY3MjISODUyMzQyMTswMDsnV"" , 
"id": "250be892-5754-ed11-8c36-000d3a8dcc52", 

code UST INONI 

"description": "Customer just said Nope and left" 


} 
PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerReturnReasons (2b0be892-5754-ed11-8c36-000d3a8dcc52) 


Example PATCH Request Body: 


"code" : "Real Cause", 
"description" : "Customer denied the purchase due to external damage" 


Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /customerReturnReasons/Sentit 
y", 

"Qodata.etag": "W/\"JzIwOzExMjQ2MDcOMzMyNj1IzMjJEwNDQIMTswMDsn\"", 

Wid Ao Obes 92—sio4 ect ll SiesiG—000dsasdees2ty, 

"code": "REAL CAUSE", 

"description": "Customer denied the purchase due to external damage" 


DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerReturnReasons (2b0be892-5754-ed11-8c36-000d3a8dcc52) 


No request body is required. No response body will be given, only an HTTP Status of 204, “No 
Content”. 
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CRUD Steps 


CREATING 


Locate the Return Reasons list. Create a new Code and Description. 


UPDATING 


To trigger an update, alter the Description field. 


DELETING 


Return Reasons can be deleted easily via the Delete action bar button. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


History 


No notable changes. 
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a oe 


Chapter 29: Customer Sales 


The customerSales endpoint is a calculated sum of the Sales (LCY) field on the Customer 
Ledger Entries table, filterable by the customer number and a date range. 


Primary Key 


N/A This API is a query that does not directly expose a table, so there is no 
Business Central primary key. Each record in the results will be unique 
per customerld. 


Field Map 


API JsoN: 


Uewisneoniereitollg Wopeitlosicilio— ee ec otiose ao T9M 
"customerNumber": "20000", 

"name"; "Trey Research", 

"totalSalesAmount": 1251, 

Weleneaiaal ibieewe IalilesicOinllys nul 


BUSINESS CENTRAL ENTITY: 
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Customer Ledger Entries 


e. 


Ø Search BE Editlist Home Entry More options 
AS 
A 
e 


Posting Date 
Document No Customer Name Amount Sales ($) 


PS-INV103197 ) Relecloud 3,081.84 2,907.40 
Payment — PS-INV103192 Relecloud -4,596.16 0.00 
Invoice PS-INV103192 Relecloud 4,596.16 4,336.00 
Payment — PS-INV103188 Relecloud -403.01 0.00 
Invoice PS-INV103188 Relecloud 403.01 380.20 
Invoice PS-INV1031... Relecloud 2,877.48 2,714.60 


oe me iàkniann470 LL 4 nn 417 ann 


Note: The name will come from the Customer Card, not the Customer Ledger Entries. So, if a 
Customer Name is adjusted, the API will reflect the current Name, not the Customer Name in 
the history. 


To get the Sales (LCY) sum for a date range, you can supply a date range filter on the 
dateFilter FilterOnly field: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/customerSales?$filter=(dateFilter FilterOnly ge 2024-03-01) 
and (dateFilter FilterOnly le 2024-03-31) 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /customerSales 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/customerSales?$filter-customerId eq 6c15971e-df3a-edll-bbae- 
6045bd8e554a 


Example GET Response (2 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/customerSales", 
"value": [ 


{ 
"customerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 
"customerNumber": "10000", 
"name": "Adatum Corporation", 
"totalSalesAmount": 223598.4, 
Udaenikse Mtem ni nu] 
), 
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"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 
"customerNumber": "20000", 

"name": "Trey Research", 

"totalSalesAmount": 58673, 

Bcaenmuserast emo nis inul 


}, 
CRUD Steps 


CREATING 


This endpoint is based on transactional data for a Customer, such as posting a Sales 
Invoice. Unfortunately, covering all the steps on how to do that is beyond the scope of this 
book. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


History 


No notable changes. 
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Chapter 30: Opportunity 


The Opportunity endpoint allows access to the Business Central CRM functionality called 
Opportunity. This is designed to keep track of potential business for a given contact. 


Note that many of the fields at this endpoint are read-only. The only fields that can be 
changed via the API are: 


e number 

e contactNumber 
e salespersonCode 
e description 


Primary Key 


No. The identifier of the Opportunity. The field is 20 characters and 
alphanumeric. 


Field Map 


API JSON: 


"Qodata.etag": "W/\"JzIwOzE4MzUwNTU5NjgyODM0MjcyMTM4MTswMDsn\"", 
"id": "77582523-df3a-edll-bbae-6045bd8e554a", 

"number": "OP100022", 

"contactNumber": "CT000002", 


"contactName": 


"Robert Townes", 


"contactCompanyName": "Adatum Corporation", 
"salespersonCode": "BC", 


"description": 


"Storage facilities", 


UisneenEUIS E. Mita S: 00/70) de herere prerexerei 
"closed": false, 
"creationDate": "2024-01-20", 


"dateClosed": 


X90 (93. —()3L.—(0 3E W , 


"calculatedCurrentValue": 100, 
"chancesOfSuccessPrc": 25, 

"completedPrc"; 2, 

"estimatedClosingDate": "2024-02-02", 
"estimatedValue": 5000, 

"systemCreatedAt": "2024-04-17T09:36:19.067", 
"lastModifiedDateTime": "2024-04-17T709:36:53.6772" 
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BUSINESS CENTRAL ENTITY: 


Opportunity Card 
OP100022 - Storage facilities 
Home ^ Opportunity Actions Automate Fewer options 


© Update $ Create Sales Quote {$ Close — [&ShowSalesQuote — & Create Interaction — [£] Postponed Interactions 


Ð Details È Attachments (0) 


No opio] number Sales Document No. v 

Description Stora description Campaign No. Statistics 

Contact No croo[ contactNumber Priority Normal 

Contact Name Robel contactName EXISTING - z 3 
stimated Vi estimatedValue 

Phone No. Status tn Pr status 


chanceOfSuccessPre 


Mobile e No. Closec e. closed 


Email robert.townes@contoso.com [ jate æf creationDate 


dateclosed urrent Value ($) [ca1culatedCurrentvalue| 


completedPrc 


Contact Company Nam: Adaty contactCompanyName 


Bc salespersonCode 


ann ne of Eman Estimated Value 
Stage Stage Description 2 


A Initial 1/25/2022 — 2/4/2022 5,000.00 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID])]))/opportunities 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/opportunities (77582523-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/opportunities", 
eue | 
{ 

"@odata.etag": "W/\"JzE50zUyNzY yMzYzNDA2MjgyNDE3MjI1xOzAwOyc=\"", 
"id": "72582523-df3a-edll-bbae-6045bd8e554a", 
"number": "OP100015", 
"contactNumber": "CT000002", 
"contactName": "Robert Townes", 
"contactCompanyName": "Adatum Corporation", 
"salespersonCode": "JO", 
"description": "Assembling furniture", 
Wigieaiebisi a Nea 
"closed": true, 
"creationDate": "2024-01-03", 
Uaec ose Uu) ue p 
"calculatedCurrentValue": 9000, 
"chancesOfSuccessPrc": 100, 
"completedPrc": 100, 
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"estimatedClosingDate": "2024-01-25", 
"estimatedValue": 9000, 

"systemCreatedAt": "2024-04-17T09:36:19.04322", 
"lastModifiedDateTime": "2024-04-17T09:36:53.5972" 


"Qodata.etag": "W/N"JzIwOzEAMzUwNTUSNjgyODMOM;j cyMTMAMTswMDsn^N"", 
"id": "77582523-df3a-edll-bbae-6045bd8e554a", 
"number": "OP100022", 

VeoOntace Number wn 990010217 

"contactName": "Robert Townes", 
"contactCompanyName": "Adatum Corporation", 
"salespersonCode": "BC", 

"description": "Storage facilities", 

UewesuepiePUg ans SOO) Toxetore parete: n 

"Closed": false, 

"creationDate": "2024-01-20", 

"dateClosed": "0001-01-01", 
"calculatedCurrentValue": 100, 
"chancesOfSuccessPrc": 25, 
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"estimatedClosingDate": "2024-02-02", 
"estimatedValue": 5000, 

"systemCreatedAt": "2024-04-17T09:36:19.067", 
"lastModifiedDateTime": "2024-04-17T09:36:53.6772" 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /opportunities 


Example POST Request Body: 


{ 
"contactNumber": "CT000002", 
Vdeseripeon [ese Trom ARTU 
"salespersonCode": "JO" 

} 


Example POST Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/opportunities/Sentity", 
"Qodata.etag": "W/\"JzIwOzE4MTc5SNTc3MzcOMjJAyNZMONTU4MTsSwMDsn\"", 
"id": "ff574ad6-86a0-ed11-9a88-6045bd02bfe0", 
"number": "OP000002", 
"contactNumber": "CT000002", 
"contactName": "Robert Townes", 
"contactCompanyName": "Adatum Corporation", 
"salespersonCode": "JO", 
Ndesemip Bion! Tesoro ABDI 
WreneenEBIS B "oi. 50/0/20) Startech, 
"closed": false, 
"creationDate": "2024-06-03", 
"dateClosed": "0001-01-01", 
"calculatedCurrentValue": 0, 
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“chancesofSuccessErc™: 0, 

"completedPrc": O0, 

"estimatedClosingDate": "0001-01-01", 
"estimatedValue": 0, 

"systemCreatedAt": "2024-06-03T11:23:27.8932", 
WiasteModaried Date lime 12024 0/6- DES aor Bose 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/opportunities(ff574ad6-86a0-ed11-9a88-6045bd02bfe0) 


Example PATCH Request Body: 


"description": "New Description from API" 


Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/opportunities/Sentity", 

"@odata.etag": "W/N"JzIWOzEAMTCS5NTC3MzcOMjAyNzMONTUAMTswMDsnN"", 

"id": "ff574ad6-86a0-ed11-9a88-6045bd02bfe0", 

"number": "OP000002", 

"contactNumber": "CT000002", 

"contactName": "Robert Townes", 

"contactCompanyName": "Adatum Corporation", 

"salespersonCode": "JO", 

"description": "New Description from API ", 

Wsieeiewisss “Minto s0/0/20)- Simei, 

"closed": false, 

NenreatilonDatke. 70 24—-0i6-O0on0, 

"dateClosed": "0001-01-01", 

"calculatedCurrentValue": 0, 

"chancesOfSuccessPrec": O0, 

"completedPrc": O0, 

"estimatedClosingDate": "0001-01-01", 

"estimatedValue": 0, 

"systemCreatedAt": "2024-06-03T11:23:27.8932", 

"lastModifiedDateTime": "2024-06-03T11:23:27.893z2" 


DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/opportunities(ff574ad6-86a0-ed11-9a88-6045bd02bfe0) 
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No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


In the Opportunities list, click on the New button in the Action Bar: 
Opportunities 


Opportunities | Ø Search -+ New Manage ¥ Activate F a 3 [B Show Sales Quote 


Creation Salesperson 
No. t Date Description Contact No. Code Status Current Sales Cycle Stage 


OP100015 1/5/2022 Assembling furniture CT000002 JO Won 
OP100016 1/5/2022 Assembling furniture CT000004 JO Won 
OP100017 1/7/2022 Assembling furniture CTO00006 OF Won 
OP100018 1/7/2022 Furniture to sales department CT000010 JO Won 
OP100019 1/1/2022 Furniture for the conference CT000002 JO Won 
OP100022 1/22/2022 Storage facilities cT000002 BC In Progress Initial 
OP100023 11/12/2021 Swivel chair CT000004 BC In Progress Initial 


OP100024 12/15/2021 Table lighting CT000006 HR In Progress Initial 


This will open a blank Opportunity Card. Click on the Description field (which should 
automatically assign a Opportunity No. - if not, enter a Opportunity No. manually) and enter 
text: 


OP000003 


Home Opportunity Actions w Automate ^^ Fewer options 


A 


¥ Activate First Stage S [i Show Sales Quote 2 Create Interaction a Postponed Interactions 


General 


No. OP000003 Sales Document No. 


Description Test Opportunity Campaign No. 


Contact No. M Priority 


Contact Name Sales Cycle Code 


m ar ec 


UPDATING 


Open an Opportunity Card from the Opportunities list and adjust the Description field. 
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DELETING 


Select the Manage button in the Action Bar from the Opportunities list and choose the 
Delete action. 


Bound Actions 


No bound actions. 


Navigations 


e contact (page 97) 


History 


| Version Changes 


19.0 Added 
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Chapter 31: Sales Credit Memos 


The Sales Credit Memos endpoint allows access to both Sales Credit Memos and Posted 
Sales Credit Memos documents. When working with this endpoint, it is strongly 
recommended to read Part 8: Chapter 88: Sales & Purchase Documents (page 506). 


Primary Key 


No. The identifier of the Sales Credit Memo or the Posted Sales Credit 
Memo. The field is 20 characters and alphanumeric. 

Posted The indication of whether the Sales Credit Memo is posted or not. The 
field is a Boolean (Yes or No) indicator. 


Field Map 


API JSON: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesCreditMemos/Sentity", 
"Qodata.etag": "W/N"JzESOzkOMTEIMzYA4ODU3MzAxMzklMDgxOzAwOyc-N"", 
tci ME »5A ed MESE oe 0/0065 ade c2 


"number ™: "S-CcRIOO01" 
"externalDocumentNumber": "", 
V essexbuiMesiDEnES di *22()—1.25E Vr 


JAsyoxenEsuekelDkeuES ug 92:910) 25 .. 
Mme auc V2 d od 
"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 


"customerNumber": "20000", 
"customerName": "Trey Research", 
"billToName": "Trey Research", 
"pillToCustomerId": "6d15971e-df3a-ed11-bbae-6045bd8e554a", 
"billToCustomerNumber": "20000", 
"sellToAddressLinel": "153 Thomas Drive", 
"sellToAddressLine2": "", 

WeyxedLilaoestiesz Ug. - Melaatexisi9^ 

"sedlttocountey s: US 

Used Testa MATT 

use llToPostCode n 61023151 
"billToAddressLinel": "153 Thomas Drive", 
"billToAddressLine2": "", 

Hoist Tblbate(o bie; d. Ela ersieo p 

Wont dlTbartererenbusiessw s Moisi 
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onmo starte 3° and 


Woa LEGROS ECOC MEMO so, 

"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 

"currencyId": "8414971e-df3a-ed11-bbae-6045bd8e554a", 
"currencyCode": "EUR", 


"paymentTermsId": "7914971e-df3a-edl11-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"salesperson": "JO", 

"pricesIncludeTax": false, 

"discountAmount": 0, 

"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 

"totalTaxAmount": 0, 

"totalAmountIncludingTax": 0, 


"statuse Dra Etsy 

WilaseModa ied Dakelime 2022 IN Zoho RA 
"invoiceld": "00000000-0000-0000-0000-000000000000", 
"invoiceNumber": "", 

"phoneNumber":; "", 

"email": "helen.ray@contoso.com", 


"customerReturnReasonId": "00000000-0000-0000-0000-000000000000" 


BUSINESS CENTRAL ENTITY: 


Sales Credit Memo 
S-CR1001 - Trey Research 


Home Prepare Request Approval Credit Memo More options 


[f Post v [2 Release v & Apply Entries... 


General Show less 


Customer No. 200 customerNumber ]v Posting Date 10/25 postingDate a 


Customer Name Trey customerName te Document Date 12/31 creditMemoDate [i 
Sell-to Due Date | 11/1/ dueDate 
Address | 153| sellToAddressLinel External Document No. externalDocumentNumber 


Address 2 | sellToAddressLine2 Salesperson Code JO 


City (Chid sellToCity pos Campaign No. bd 
State IL sellToState Responsibility Center 
ZIP Code \612{ sell ToPostCode |- Assigned User ID | v 


Country/Region [US sellToCountry SE Status Opi ^ status X ] 


Contact No. CT000003 


Phone No. phoneNumber Applies-to Doc. No. 


Mobile Phone No. 


Applies-to Doc. Type v 


Applies-to ID 


Email wey email | work Description 
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Manage Functions Line Fewer options 
Item Reference Unit of 
No. Description Location Code Quantity Measure Code 
PARIS Guest Chair, black PCS 
ANTWERP Conference Table PCS 


Subtotal Excl. Tax (EUR) 1,232.11 Total Excl. Tax (EUR) totalAmountExcludingTax 


Inv. Discount Amount Excl. ... discountAmount 0.00 Total Tax (EUR) total TaxAmount 


Invoice Discount % 0 Total Incl. Tax (EUR) totalAmountIncludingTax 


Credit Memo Details 


Currency Code EUR currencyCode et Tax Area Code CHICAGO, IL 


Company Bank Account Co... Tax Liable «o 


Show less 


Shipment Date Department Code sA shortcutDimensionlCode 


VAT Bus. Posting Group Customergroup Code MishortcutDimension2Code 


Customer Posting Group DOMESTIC Payment Discount 96 
Payment Terms Code 14 DAYS Pmt. Discount Date 


Payment Method Code Location Code 


Billing 


Bill-to 


Name Trey Resé billToName 


Address 153 Thon billToAddressLinel 


Address 2 billToAddressLine2 


City Chicago billTocity 


State billToState 


ZIP Code billToPostCode 


Country/Region l billToCountry 


Contact No CT000003 


There are some fields that are not exposed on the page by default or entirely, such as the 
customerReturnReasonId and shipmentMethodId. 


GET 


Example GET Request URI List: 
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https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesCreditMemos 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/salesCreditMemos (f2bddf9a-5b54-ed11-8c36-000d3a8dcc52) 


Example GET Response (1 entity shown from a longer list): 


{ 


"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({ {companyID}})/salesCreditMemos", 
"value": [ 


{ 
"Qodata.etag": "W/N"JzESOzkOMTEIMzY4ODU3MzAxMzk1MDgxOzAwOyc-N"", 
"id": "f2bddf9a-5b54-ed11-8c36-000d3a8dcc52", 


numb eS CR IOONE 
"externalDocumentNumber": "", 
"creditMemoDate": "2020-12-31", 


Jheroxenesusxepbeue wg 20d es 
Vauebake UT 
"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 


"customerNumber": "20000", 
"customerName": "Trey Research", 
"billToName": "Trey Research", 
"pillToCustomerId": "6d15971e-df3a-edl11-bbae-6045bd8e554a", 
"billToCustomerNumber": "20000", 
"sellToAddressLinel1": "153 Thomas Drive", 
"sellToAddressLine2": "", 

MexedbuexesbES ys EMC aou, 

use lToCountr ya: WU Su 

Lsnlibitoysieeiec Ye) T, 

NsellMoPestCodels od? 35i" 
"pillToAddressLinel": "153 Thomas Drive", 
"pillToAddressLine2": "", 

MonLibiktocaticy Ug MOlsatesceo 

Went ddbarsrereuimEss S Ve 

Ujonlibiineysicenec MOTTO 

IU WNISINTCIE OS GC MEMO sou, 
"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 
"currencyId": "8414971e-df3a-edll-bbae-6045bd8e554a", 
"curneneyecode  UEURPS, 


"paymentTermsId": "7914971e-df3a-ed11-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
Wsalespenson MU 

"pricesIncludeTax": false, 

"discountAmount": O0, 

"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 

WEOwa ess: 07 
NeotalAnounitinelucding Masa: 10), 

WSE aest MDDr EES, 

WilastModitredbatetame 2022-02 Sikes ario Om 
"invoicelId": "00000000-0000-0000-0000-000000000000", 


"invoiceNumber": "", 
"phoneNumber":; "", 
"email": "helen.ray@contoso.com", 


"customerReturnReasonId": "00000000-0000-0000-0000-000000000000" 
), 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesCreditMemos 


Example POST Request Body: 


"creditMemoDate": "2024-05-28", 
"customerNumber": "20000", 
"currencyCode": "EUR" 


Example POST Response: 


{ 


"@odata.context": 


"https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 


/APIBook/api/v2.0/S$metadata#companies ({ {companyID}})/salesCreditMemos/Sentity", 
ExMDU1MjcOMzgxNzkOODI3NTcwMTswMDsn'N"", 


"Qodata.etag": "W/N"JzIwOzl 
Wiel 2 
mumboert: m S-emIN)02 

"externalDocumentNumber": 
"creditMemoDate": 
"postingDate": 
"dueDate": "2024-5-28", 
"customerId": 
"customerNumber": 
"customerName": 
illToName": 
illToCustomerId": 
"billToCustomerNumber": 
"sellToAddressLinel": 


r2 OQ , 


"sellToAddressLine2": "", 
WUeyxedLbaoestiev Us else (eo , 
usel ToCountr yd JUSH, 
mselllostave TN 
DSeuNNToOPcsis 99e 6] 961 


"pillToAddressLinel": 


"7a08b0da-5b54-ed11-8c36-000d3a8dcc52", 


"wn 
, 


120242. 05. 2994 
1/210)2:71—(15—(0) 547. 


"6d15971e-df3a-ed11-bbae-6045bd8e554a", 


"Trey Research", 

"Trey Research", 
"6d15971e-df3a-edll-bbae-6045bd8e554a", 
1521010100177 

W115:9) aaroniels: Iie we 


"153 Thomas Drive", 


Noi Monddresisinmne2 t: m" 

Hom OCETA WE SECON y 

Wien SCS E S 
Ing S Stoico: TN 

"ies dl dbarsyeexsie(e xot ts WOW SIG 
"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 


"currencyId": "8414971e-df3a-edl11-bbae-6045bd8e554a", 
"currencyCode": "EUR", 

"paymentTermsId": "7914971e-df3a-ed1l1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"salesperson": "JO", 

"pricesIncludeTax": false, 

NeiscouneAmounitn 10! 

"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 

"totalTaxAmount": 07 

"totalAmountIncludingTax": 0, 


Ursneelebis! 3 MiDiseubiE M n 


"lastModifiedDateTime": 
"00000000-0000-0000-0000-000000000000", 


OEE 
"invoiceNumber": 
"phoneNumber"; "", 


woe 
, 


:202/21—(0)15 (0.5 HEXETE 3:5)5) 8:510) c sia, 
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"email": "helen.ray@contoso.com", 
"customerReturnReasonId": "00000000-0000-0000-0000-000000000000" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesCreditMemos (7a08b0da-5b54-ed11-8c36-000d3a8dcc52) 


Example PATCH Request Body: 


JMerexste mueren B. 072109) 2:21—(0)55 $0) 4 7 
vdueDatet: 2027-96: 0/9 
"customerNumber": "30000" 


Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesCreditMemos/Sentity", 

"Qodata.etag": "W/\"JzIwOzEyMzM2NDUWODkIMTYyNZQOODMS5MTswMDsn\"", 

Wid a0sb0da-sbo4—edtl—ses6—000dsasdees2, 

"number": "S-CR1002", 

"externalDocumentNumber": "", 

"creditMemoDate": "2024-05-30", 

Uisorsiesime Denes ANZ (S0) n 

"dueDate": "2024-05-30", 

"customerId": "6e15971e-df3a-edll-bbae-6045bd8e554a", 


"customerNumber": "30000", 

"customerName": "School of Fine Art", 
"billToName": "School of Fine Art", 
"billToCustomerId": "6e15971e-df3a-edll-bbae-6045bd8e554a", 
"billToCustomerNumber": "30000", 
"sellToAddressLinel": "10 High Tower Green", 
"sellToAddressLine2": "", 

Nsegsumocastevau T UM ami 

Used TocouniGVaM NUS 

Inset: c EIU 

Useuusnobosieoceu I 
"billToAddressLinel": "10 High Tower Green", 
"billToAddressLine2": "", 

"estilos a. Wires. 

TEMO Conner ya MU. 

Wiophiibtoysecine Ye BIN 

Uum opPosit: eoo NUI 
"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "LARGE", 
"currencyId": "00000000-0000-0000-0000-000000000000", 
"currencyGcode": "USD" 


"paymentTermsId": "8114971e-df3a-edll1-bbae-6045bd8e554a", 

"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 

"salesperson": "JO", 

"pricesIncludeTax": false, 

"discountAmount": O0, 

"discountAppliedBeforeTax": false, 

"totalAmountExcludingTax": 0, 

"totalTaxAmount": 0, ) 
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"totalAmountIncludingTax": 0, 


Wicieiebis DERE 

"lastModifiedDateTime": "2024-06-03T11:42:04.9672", 
"invoiceld": "00000000-0000-0000-0000-000000000000", 
"invoiceNumber": "", 

"phoneNumber":; "", 

"email": "meagan.bond@contoso.com", 


"customerReturnReasonId": "00000000-0000-0000-0000-000000000000" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesCreditMemos (7a08b0da-5b54-ed11-8c36-000d3a8dcc52) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


Note that since this can allow deletion of Posted Sales Credit Memos, deletion may fail 
depending on system setting constraints on posted documents. 


CRUD Steps 


CREATING 


From the Sales Credit Memos list, click on the New button in the Action Bar: 


Sales Credit Memos: — All v | JO Search -+ New lil] Delete [2 Release | (iif Post | v Credit Memo v 


External 
Sell-to Document 
No. 1 Customer No. Sell-to Customer Name No. Sell-to Contact Posting Date 


S-CR1001 : 20000 Trey Research Helen Ray 10/25/2022 


This will open a blank Sales Credit Memo card. Select a Customer, which should 
automatically assign a Sales Credit Memo No. 
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Sales Credit Memo 


Home Prepare Request Approval Credit Memo More options 


[if Post | ^ [È Release | v &) Apply Entries... 


General Show more 


Customer Name * n Due Date 


Contact Status 


Posting Date 


Manage Functions Line Fewer options 


Item Reference 
No. Description Location Code Quantity 


Filling out a Sales Credit Memo is beyond the scope of this book, but this way creates it 
enough to be available for the API. 


UPDATING 


Change a field in the General section, such as the Due Date. 


DELETING 


An unposted Sales Credit Memo can simply be deleted via the Delete action in the Action 
Bar. Posted Sales Credit Memos might be deleted, but that depends on system configuration. 


Bound Actions 


e cancelAndSend 


e cancel 

e postAndSend 
e post 

e send 


e customers (page 110) 
e countryRegion (page 402) 
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e currencies (page 407) 

e paymentTerms (page 445) 

e shipmentMethods (page 457) 

e salesCreditMemoLines (page 161) 
e pdfDocument (page 450) 

e dimensionSetLines (page 427) 

e attachments (page 378) 


Changes 
Removed an enforcement mechanism that ensured the Customer information 


matched against Customer Templates 
Added Dimension fields to the API 
Added Customer Return Reason support 
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Chapter 32: Sales Credit Memo Lines 


The Sales Credit Memo Lines endpoint allows access to both Sales Credit Memo Lines 
and Posted Sales Credit Memo Lines. When working with this endpoint, it is strongly 
recommended to read Part 8: Chapter 88: Sales & Purchase Documents (page 506). 


Primary Key 


Document Id The generated identifier for the Sales Credit Memo or Posted Sales 
Credit Memo. The field is a GUID. It is locked and managed by BC. 
Line No. Integer Identifier. 


Note that this is an aggregate table, so this often comes from a Document Line table with 
a primary key of Document No. and Line No., but the aggregate table uses the Document Id 
to ensure uniqueness. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /salesCreditMemos (f2bddf9a- 
5b54-ed11-8c36-000d3a8dcc52) /salesCreditMemoLines/Sentity", 

"Qodata.etag": "W/\"JzIwOzEwMTgOMTUxMzZA5NTY5MTE2OTUyMTswMDsn\"", 

morada 565b eii sesoz000 9 23566/91]9957 

"documentId": "f2bddf9a-5b54-ed11-8c36-000d3a8dcc52", 

"sequence": 10000, 

"itemId": "7715971e-df3a-edll-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 

"description": "PARIS Guest Chair, black", 
"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


"hpngiatietese trece: eS qs 

gouam EVAS 

"discountAmount": O0, 
"discountPercent": 0, 
"discountAppliedBeforeTax": false, 
WamouncEnxcludineghasxu | ool PROP 
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Intaxcodem  hURNTLURE 

"taxPercent": 5.00009, 

"totallaxAmount": 297006, 

Veto mimic tine kuichtinewer<s Pb 
"invoiceDiscountAllocation": 0, 

Wincisinomenes SONT EO 

"netTaxAmount": 29.06, 

"netAmountIncludingTax": 610.25, 

"shipmentDate": "2024-04-01", 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


BUSINESS CENTRAL ENTITY: 


Tax Group 


> Item : - PARIS Guest Chair, black 193.73 CHICAGO,IL FURNITURE 


Item - ANTWERP Conference Table 650.924 CHICAGO, IL FURNITURE 


A variety of fields are either unavailable on the Page by default or are unavailable to 
personalize onto the page. Some fields are available only by their Id value and not code, such 
as the 1ocationId / Location Code. 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/salesCreditMemos (f2bddf9a-5b54-ed11-8c36- 
000d3a8dcc52) /salesCreditMemoLines 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/salesCreditMemos (f2bddf9a-5b54-ed11-8c36- 
000d3a8dcc52) /salesCreditMemoLines (1b7aa356-0£55-ed11-8c36-000d3a8dc661) 


Example GET Request URI Single (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/salesCreditMemoLines (1b7aa356-0£55-ed11-8c36-000d3a8dc661) 


Example GET Response (2 entities shown from a longer list from one Sales Credit Memo): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies (((companyID]))/salesCreditMemos (f2bddf9a- 
5b54-ed11-8c36-000d3a8dcc52)/salesCreditMemoLines", 

"value": [ 


{ 
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"Qodata.etag": "W/N"JzIWOzEwMTgOMTUxMzASNTY5MTE2O0TUyMTswMDsnV"", 
Waele Wille) ad5oOfb5 eii sess cS a5 ECEE, 

"documentId": "f2bddf9a-5b54-ed11-8c36-000d3a8dcc52", 
"sequence": 10000, 

"itemId": "7715971e-df3a-ed1l1-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 

"description": "PARIS Guest Chair, black", 
"unitOfMeasureId": "e415971e-df3a-edl1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


"Un EBErTCE Alleys. QUSE 

JeneWEaiw S S 

"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
WaMoOumEnsccleucamnghascu n SSmi 

UTE CECENE A ANEINORI A 

"taxPercent": 5.00009, 

WeOtallaxAmount': 29.067 

Jeimexstau e dbowerdboxebstosre tiens 9 B. Godkl0 o Zo), 
"invoiceDiscountAllocation": 0, 

"netAmount": 581.19, 

"netTaxAmount": 29.06, 

"netAmountIncludingTax": 610.25, 

"shipmentDate": "2024-04-11", 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


"Qodata.etag": "W/N"JzIWOzE2NTY5NDIyODY2NjY5MDQ1MzAwMTswMDsnN"", 
Wig "5aZzaiese—0£55-ed lll sic8o-00 0dsasdecou, 

"documentId": "f2bddf9a-5b54-ed11-8c36-000d3a8dcc52", 
"sequence": 20000, 

"itemId": "7a15971e-df3a-ed1l1-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1920-S", 

"description": "ANTWERP Conference Table", 
"unitOfMeasureId": "e415971e-df3a-edll1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


NoomusJp nuces Gon 922 

Wreqicioicaliew M B. JL 

"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
“amount Exe ludinmglaxs B. (5:0! 9) 27 

tace occ Uh URN: LU RIB, 

WraxPercemts! 5.000617 

WeOtallaxAmounti S22 55), 

"amountIncludingTax": 683.47, 
"invoiceDiscountAllocation": 0, 

"netAmount": 650.92, 

"net LaxAMouni 92 55» 

"netAmountIncludingTax": 683.47, 

"shipmentDate": "2024-04-11", 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


), 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesCreditMemos (f2bddf9a-5b54-ed11-8c36- 
000d3a8dcc52) /salesCreditMemoLines 


Example POST Request Body: 


"lineType": "Item", 
"lineObjectNumber": "1925-W", 
"unitOfMeasureCode": "PCS", 


Uriravabe dre aee B. SOO 
"discountPercent": 15, 
coant (ex 9 E 5) 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies (((companyID]))/salesCreditMemos (f2bddf9a- 
5b54-ed11-8c36-000d3a8dcc52) /salesCreditMemoLines/Sentity", 

"Qodata.etag": "W/\"JzZE5OZU0NTOzZMj k2MTOyMTEZOTMZNzcxOzAwOyc=\"", 

"id": "b0b0c021-1055-ed11-8c36-000d3a8dc661", 

"documentId": "f2bddf9a-5b54-ed11-8c36-000d3a8dcc52", 

"sequence": 30000, 

"itemId": "7515971e-df3a-ed11-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1925-W", 

"description": "Conference Bundle 1-6", 

"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


JpiguatiEje seats. S100] 

MewileWenESHESZ M B S 

icis onte Amon: 225" 

"discountPercent": 15, 

"discountAppliedBeforeTax": false, 

amos ucunmgmTasc ias 

vEaxcodel: ME UENIUGBUERBU 

ItaxPercenmnt': 5, 

vota ltTaxAmount 4: 63. 15, 

Camount neludimol laxk dE SIS TS 
"invoiceDiscountAllocation": 0, 

"netAmount": 1275, 

"netTaxAmount": 63.75, 

"netAmountIncludingTax": 1338.75, 

"shipmentDate": "2024-05-26", 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 
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PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesCreditMemos (8a3d7582-26ca-ec11-9617- 
cb648af3a4e2) /salesCreditMemoLines (0bdd801e-4bca-eci1-9617-cb648af3a4e2) 


Example PATCH Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesCreditMemoLines (b0b0c021-1055-ed11-8c36-00083a8dc661) 


Example PATCH Request Body: 


eame eya S. 
"discountPercent": 25 


Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/$metadata#companies ({{companyID}})/salesCreditMemos (f2bddf9a- 
5b54-ed11-8c36-000d3a8dcc52) /salesCreditMemoLines/Sentity", 

"Qodata.etag": "W/\"JzZE50zY5MDI3Mjg1MjA3Nzg4MTOyNjIxOzAwOyc=\"", 

"id": "b0b0c021-1055-ed11-8c36-000d3a8dc661", 

"documentId": "f2bddf9a-5b54-ed11-8c36-000d3a8dcc52", 

"sequence": 30000, 

"itemId": "7515971e-df3a-ed11-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1925-W", 

"description": "Conference Bundle 1-6", 

"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


Vhpngiatietexeat yere S40) 

“ouant eyano 

"discountAmount": 750, 
"discountPercent": 25, 
"discountAppliedBeforeTax": false, 
Nm eyunmte Bises ua 555: 2250 
I"taxcodem UEURNUDURE', 
Vigrse-seresctefeiott B. Sr 
VrotallaxAmoumt SIN 2 oO; 
Hamoun ine ludimolkaxs mee S02 cory 
"invoiceDiscountAllocation": 0, 
"netAmount": 2250, 
"netTaxAmount": 112.5, 

"netAmountIncludingTax": 2362.5, 

"shipmentDate": "2024-05-26", 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesCreditMemos (f2bddf9a-5b54-ed11-8c36- 
000d3a8dcc52) /salesCreditMemoLines (b0b0c021-1055-ed11-8c36-000d3a8dc661) 


Example DELETE Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesCreditMemoLines (b0b0c021-1055-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


Unposted Sales Credit Memo Lines can be created manually, though the particulars of 
creating Sales Credit Memos are beyond the scope of this book. If the line has some 
information populated, it should be available via the API. 


UPDATING 
Adjusting any field on an unposted Sales Credit Memo Line, such as the description, will 
update the line. 


DELETING 


Any unposted Sales Credit Memo Line may be deleted, though some business restrictions 
may prevent removal. 


Bound Actions 


No bound actions. 


e salesCreditMemos (page 152) 
e items (page 323) 
e accounts (page 38) 
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e unitsOfMeasure (page 471) 
e itemVariants (page 339) 
e dimensionSetLines (page 427) 


History 
[Version Changes j§. 
18.1 Location added. 
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Chapter 33: Sales Invoices 


The Sales Invoices endpoint allows access to both Sales Invoices and Posted Sales 
Invoices documents. When working with this endpoint, it is strongly recommended to read 
Part 8: Chapter 88: Sales & Purchase Documents (page 506). 


Note: With this endpoint, a large amount of data is available, so it 
is key to consider using smart $£ilter and $select options. 
See Part 8: Chapter 89: Performance (page 511) and Part 1: 
Chapter 2: Reading / GET (page 17) for more information. 


Primary Key 


No. The number of the Sales Invoice. The field is 20 characters and 
alphanumeric. 

Posted The indication of whether the Sales Invoice is posted or not. The field 
is a Boolean (Yes or No) indicator. 


Field Map 


API JSON: 


{ 


"@odata.context": 


"https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 


/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/salesInvoices/Sentity", 


"@odata.etag": 


"W/N"JzIwOzEwNzUOMzczMjOlMT 


EzMDMyODI 


"id": "10251e29-df3a-ed11-bbae-6045bd8e554a", 


Wiagbiglo(exel a | MES 


INV103001", 


"externalDocumentNumber": "", 


"invoiceDate": 
"postingDate": 


202 3-—(1 —1 79. 
On OS 


tauepates t0] 9 ORE 
“promisedPaybate”. 2025-0] 1 
"customerPurchaseOrderReference"; "", 
"6d15971e-df3a-edl1-bbae-6045bd8e554a", 
"customerNumber": "20000", 


"customerId": 


"customerName": 


"Trey Research", 


"billToName": "Trey Research", 
"bpillToCustomerId": 
"billToCustomerNumber": "20000", 


E3MTswMDsnN"", 


"6d15971e-df3a-edll-bbae-6045bd8e554a", ) 
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Pace C3 (168 


"shipToName": "Trey Research", 

"shipToContact": "Helen Ray", 

"sellToAddressLinel": "153 Thomas Drive", 
"sellToAddressLine2": "", 

Verede(Cubs7/8 Wear 

"sellToCountry": "US", 

Iseuumositan: e EIUS 

Useussnobosiseoceu: 67235 

"billToAddressLinel": "153 Thomas Drive", 
"billToAddressLine2": "", 

Wiestdblbarexestqsy; 8 — (Elgar o 

Men IiMtocouinciey S Mus 

INN Sac Wari 

“bi liToPost€ode™: 612396", 

"shipToAddressLinel": "153 Thomas Drive", 
"shipToAddressLine2": "", 

dsygasuolcabigsz es Wilma eise 

vshiphocounmer yas MOT M 

Shiki LO Sica eam lanl 

UsinsjoMworosirCoca"s Wied Asie! 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 

UcucrencytodeVv USD 

"orderId": "00000000-0000-0000-0000-000000000000", 
"orderNumber": "", 

"paymentTermsId": "8214971e-df3a-ed11-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 


salesperson k qe go 
tearsputesStacus (DA. UU 

B ciues iste m u 
"pricesIncludeTax": false, 
"remainingAmount": 0, 


"discountAmount": 0, 
"discountAppliedBeforeTax": true, 
"totalAmountExcludingTax": 164.7, 
"totalTaxAmount": 8.24, 
"totalAmountIncludingTax": 172.94, 


ustacus tn Parda, 

"lastModifiedDateTime": "2024-04-17T09:37:40.6222", 
"phoneNumber":; "", 

"email": "helen.ray@contoso.com" 


BUSINESS CENTRAL ENTITY: 


Robert Townes 

iVv102200 Adatum Corporation Robert Townes 
S-INV102201 Trey Research Helen Ray 

S-INV 102202 3000 School of Fine Art Meagan Bond 


School of Fine Art Meagan Bond 


iaa Mahara 
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les Invoice J E + iol 


S-INV102199 - Adatum Corporation 

Home Prepare Request Approval Invoice More opt © 
General — 
Customer No customerNumber Your Reference OPEN 


ustomer Name customerName Document Date 
Address sellToAddressLinel Due Date 
Address ; sellToAddressLine2 External Document No 
City sellToCity Salesperson Code 


State sellToState ampaign No 

ZIP Code sellToPostCode Responsibility Cente 

Country/Region Code sellToCountr Assigned User if 

Contact Nc CTO00001 tatu status 

Phone No phoneNumber Work Description 

i 

Contact Robert Townes 

Lines Manage Line Fewer options eg 

Tee No D Lr Description ocation Code Quantity Mans we Code us; p Tax Area Code 

> |tem i 1968-5 MEXICO. Swivel Chair. black S PCS 190.10 ATLANTA GA 
Item 1996-S ATLANTA Whiteboard, base 7 PCS 1397.30 ATLANTA GA 


Comment Thank you for ordering 


v. Discou t Exel, Tax discountAmount 0.00 Total Tax (USC totalTaxAmount 
Invoice Discount % 0 Total inci. Tax (USD totalAmountIncludingTax 


‘ " 
Subtotal Exel. Tax (USD 1073160 Total Exel. Tax (USD) totalAmountExcludingTax 
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Invoice Details 


currencyCode as Payment Service No payment service is made available 
9/23/2022 


shortcutDimensionlCode 


mergroup Code shortcutDimension2Code 


x 
5 
t 
D 
| 
‘ 


wp-to Custom Address Bill-to Custom Address 
Shipment Method Phone No 


Code Motde Phone No 
Agent Em 


Agent service 


Package Tracking No 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesInvoices 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/salesInvoices (10251e29-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (1 entity shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/salesInvoices", 
"value": [ 
{ 


"Qodata.etag": "W/\"JzIwOzEwNzU0MzczMjQ1MTEZMDMyODE3MTswMDsn\"", 
"id": "10251e29-df3a-edl1-bbae-6045bd8e554a", 
Voromlb esc WETS ETN OSNO 
"externalDocumentNumber": "", 

LslionOalee Drie T 29) 24 (9) 3L 74 
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IsOpen a 07s ULT 

Weliepence a 20) zal ily 7 

“promusedPaybDate | "2023-—0m—i7 
"customerPurchaseOrderReference": "", 

"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 
"customerNumber": "20000", 

"customerName": "Trey Research", 

"billToName": "Trey Research", 

"billToCustomerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 
"billToCustomerNumber": "20000", 

"shipToName": "Trey Research", 

"shipToContact": "Helen Ray", 

"sellToAddressLinel": "153 Thomas Drive", 
"sellToAddressLine2": "", 

Jeyeddbmojostigs Us Wielaattexieio 

Ws Cuneo. Oui ta yeu Sie, 

Mselillostaces TN 

Ws elMuloPostcCodets 6029/61 

"pillToAddressLinel1": "153 Thomas Drive", 
"billToAddressLine2": "", 

Toroi tys a WCiaaiererefo 

Cpo CouUnery ys Musi 

vpilitostatet: STEN 

TomTo EROSETCOCEN WE SU n 

"shipToAddressLinel": "153 Thomas Drive", 
"shipToAddressLine2": "", 

JisimugsueleatiEs7 s. Wil agon, 

Msn eot ya MIU 

sire SIS edis m MD 

UshuplOoPost Codes: 612 316, 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 

WeurnencyCode" e USDE, 

"orderId": "00000000-0000-0000-0000-000000000000", 
"orderNumber": "", 

"paymentTermsId": "8214971e-df3a-edll1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 


"salesperson": "JO", 
Melitesse eue Dus TDN A US 
"spe oisautsus d WUT 
"pricesIncludeTax": false, 
"remainingAmount": 0, 


voi seountZmountis: 
"discountAppliedBeforeTax": true, 
"totalAmountExcludingTax": 164.7, 
Grota MaxAmount i: DEP 
VeOealAnount me luding las: on" 


“status t: "Paid, 

"lastModifiedDateTime": "2024-04-17T09:37:40.6222", 
"phoneNumber": "", 

"email": "helen.ray(8contoso.com" 


), 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesInvoices 


Example POST Request Body: 
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"customerNumber": "10000", 
WAiMvOlee Dawe o mo 
cho Denes VOOAA op Qt 


Extra Example POST Request Body (With Sales Invoice Lines): 


"customerNumber": "10000", 
"salesInvoiceLines" : [ 


{ 


"lineType": "Ttem", 
"lineObjectNumber": "1996-S", 
Uig(iciaiciiey Ye ib 


Example POST Response (Without Sales Invoice Lines): 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({{companyID}})/salesInvoices/S$entity", 
"Qodata.etag": "W/\"JzE50zM50DQ040TA30TA3NDA2Njg2NjMxOzAwOyc=\"", 
"id": "5e7604f6-1155-ed11-8c36-000d3a8dc661", 
umnumoe ra a tS al NANO a 
"externalDocumentNumber": "", 
"invoiceDate": "2024-04-20", 
"postingDate": "2024-06-03", 
"dueDate": "2024-05-20", 
"promisedPayDate": "2023-01-17", 
"customerPurchaseOrderReference": "", 
"customerId": "6c15971e-df3a-edl1-bbae-6045bd8e554a", 
"customerNumber": "10000", 
"customerName": "Adatum Corporation", 
"billToName": "Adatum Corporation", 
"billToCustomerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 
"billToCustomerNumber": "10000", 
"shipToName": "Adatum Corporation", 
ToContact": "Robert Townes", 
"sellToAddressLinel": "192 Market Square", 
"sellToAddressLine2": "", 
Use Uno va MENACES T M 
Insee oun US 
"sellToState": "GA", 
Liliveiesiitecickets WS AW 
"billToAddressLinel": "192 Market Square", 
"billToAddressLine2": "", 
Vode oCare yw AE TL EU 
Hon IIikecoumeey Ss MUS E 
IUSSIT Sedi SCAU 
Inge oS oce ME SU 
"shipToAddressLinel": "192 Market Square", 
"shipToAddressLine2": "", 
vshiphocitye T ANE Tau 7 
Weslaayomecroruimtereyel sg Moissy, 
“shipTrogtaten: MEAN 
ZSPiDIOROSCCOCE NE AST 
"currencyId": "00000000-0000-0000-0000-000000000000", 
"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "SMALL", 
Vewunnencyicode ls USDE, 
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"orderId": "00000000-0000-0000-0000-000000000000", 
"orderNumber": "", 

"paymentTermsId": "7b14971e-df3a-edl1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 


"salespersonVW: “JOM, 

NGS PINES Scent uis DN ay eu, 
tdisputestatust: UM 
"pricesIncludeTax": false, 
"remainingAmount": 0, 


"discountAmount": O0, 
"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 
"totalTaxAmount": 0, 
"totalAmountIncludingTax": 0, 


Instead MTS aste 

"lastModifiedDateTime": "2024-06-03T12:47:33.1332", 
"phoneNumber":; "", 

"email": "robert.townes(contoso.com" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesInvoices (5e7604f6-1155-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


"customerNumber": "20000", 
Wimvyoueebatce n2 02-952 5) 
"dueDate": "2024-11-25" 


Example PATCH Response: 


{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/salesInvoices/Sentity", 

"Qodata.etag": "W/\"JzIwOzExMzkyOTOINjJU2NTk4NDg1NzOxMTswMDsn\"", 

"id": "5e7604f6-1155-ed11-8c36-000d3a8dc661", 

Wioibiilorwet ss MSSTNVI02222u 

"externalDocumentNumber": "", 

IM VONeeD ate m qoM 

UsOsieiime Dees VA0Z4LO=264 

"dueDate": "2024-11-08", 

"promisedPayDate": "2024-11-08", 

"customerPurchaseOrderReference": "", 

"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 

"customerNumber": "20000", 

"customerName": "Trey Research", 

"billToName": "Trey Research", 

"billToCustomerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 

"billToCustomerNumber": "20000", 

"shipToName": "Trey Research", 

"shipToContact": "Helen Ray", 

"sellToAddressLinel": "153 Thomas Drive", 

"sellToAddressLine2": "", 

WeyedbibanorestiEv s s. Melaatersie o 7 

seussnoconntcy SM ) 
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MSIL Siechice CTL 

nsedlltobosi eodem ooo 

"pillToAddressLinel1": "153 Thomas Drive", 
"billToAddressLine2": "", 

Joy ddbgeXCsbtisz48 Wels" y 

Wen LiMnocouimrew S MAIS 

Ionio Seco a Mini 

"Vie dlclbareyelexsEC xot a - WWE» SIG 

"shipToAddressLinel": "153 Thomas Drive", 
"shipToAddressLine2": "", 

Viglen E WMeliiecco", 

Hesinsjowocomimtemay g. ost, 

“ship lostatet S. UIDI 

UshiploPost€odell: 61296" 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 

NeurnencyCodel: m US 

"orderId": "00000000-0000-0000-0000-000000000000", 
"orderNumber": "", 

"paymentTermsId": "7914971e-df3a-edl1l-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 


“salesperson Se 
voaisputegtacts THN WAN 
taisputestatush: au 
"pricesIncludeTax": false, 
"remainingAmount": 0, 


"discountAmount": O0, 
"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 

It:o tau dccATmoun t: 07 
"totalAmountIncludingTax": 0, 


voides er Mlphsrzurie 

"lastModifiedDateTime": "2024-06-03T12:50:13.1472", 
"phoneNumber":; "", 

"email": "helen.ray@contoso.com" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/salesInvoices (5e7604£6-1155-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


From the Sales Invoices list, click on the New button in the Action Bar. 
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Sales Invoices: 


JO Search 


+ New 


lii] Delete 


[ii Post 


Invoice ^^ 


[2 Release | v 


No. 1 

S-INV102199 
S-INV102200 
S-INV102201 
S-INV102202 


S-INV102203 


Sell-to 
Customer 


10000 
10000 
20000 
30000 


30000 


No. 


Sell-to Customer Name 


Adatum Corporation 


Adatum Corporation 
Trey Research 
School of Fine Art 


School of Fine Art 


External 
Document 
No Sell-to Contact 


Robert Townes 
Robert Townes 
Helen Ray 

Meagan Bond 


Meagan Bond 


More options 


As: 
Location Code ID 


Posting Date 
4/4/2022 
5/1/2022 
4/3/2022 
4/5/2022 


5/13/2022 


This will open a blank Sales Invoice card. Select a Customer, which should automatically 
assign a Sales Invoice No. 


Sales Invoice 


Home Prepare Request Approval Invoice Actions Related Automate Fewer options 


lait Post 


General 


Customer Name Due Date 


Contact Status 


Posting Date 


Lines Manage Line Fewer options 

Item Unit of 
Reference 

No. Description 


Unit Price Tax Area 


Excl. Tax 


Measure 
Quantity Code 


Location Tax Group 


Code Code Code 


Filling out a Sales Invoice is beyond the scope of this book, but this method creates it 
enough to be available for the API. 


UPDATING 


Change a field in the General section, such as the Due Date. 


DELETING 


An unposted Sales Invoice can simply be deleted via the Delete action in the Action Bar. 
Posted Sales Invoices might be deleted, but that depends on system configuration. 
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Bound Actions 


cancelAndSend 

cancel 
makeCorrectiveCreditMemo 
postAndSend 

post 


Navigations 


customers (page 110) 
countryRegion (page 402) 
currencies (page 407) 
paymentTerms (page 445) 
shipmentMethods (page 457) 
pdfDocument (page 450) 
attachments (page 378) 
dimensionSetLines (page 427) 


History 


Changes 

24.0 Fields Added: promisedPayDate, disputeStatusld, disputeStatus 

21.0 Removed an enforcement mechanism that ensured the Customer information 
matched against Customer Templates. 

19.0 Added Dimension fields to the API. 
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Chapter 34: Sales Invoice Lines 


The Sales Invoice Lines endpoint allows access to both Sales Invoice Lines and Posted 
Sales Invoice Lines. When working with this endpoint, it is strongly recommended to read Part 
8: Chapter 88: Sales & Purchase Documents (page 506). 


Primary Key 


Document Id The generated identifier for the Sales Invoice Line. The field is a GUID. It 
is locked and managed by BC. 
Line No. The numeric identifier for the specific Sales Invoice Line. It is unique only 


in the given Sales Invoice. 
Integer Identifier. 


Note that this is an aggregate table, so this often comes from a Document Line table with 
a primary key of Document No. and Line No., but the aggregate table uses the Document Id 
to ensure uniqueness. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /salesInvoices (5e7604f6-1155- 
ed11-8c36-000d3a8dc661) /salesInvoiceLines/Sentity", 

"Qodata.etag": "W/\"JzE50zgzNzA2NTYS50TEOMDUZNTI4MzUxOzAwOyc=\"", 

Waele UC ee ASS med 1k 9520/9065 96/9/0915 

"documentId": "5e7604f6-1155-ed11-8c36-000d3a8dc661", 

"sequence": 10000, 

"itemId": "7e15971e-df3a-ed11-bbae-6045bd8e554a", 


"accountId": "00000000-0000-0000-0000-000000000000", 
"lineType": "Item", 

"lineObjectNumber": "1936-S", 

"description": "BERLIN Guest Chair, yellow", 
Wielosiosealioieavendi2ig WW. 

"unitOfMeasureId": "e415971e-df3a-edl1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


umie percen IC S 
goguan tieva te 
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"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
Wamountbecelucdimeg lars) sii) Were, 

EaxCOCeusa nh ENIIEDUEBM 

WtaxPercenits 57 

InttorEa mas Amount: 387367 

"amountIncludingTax": 809.76, 
"invoiceDiscountAllocation": O0, 

"netAmount": 771.2, 

"netTaxAmount": 38.56, 

"netAmountIncludingTax": 809.76, 

"shupmentDbatew: 2024-10-26 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


BUSINESS CENTRAL ENTITY: 


S-INV102199 - Adatum Corporation 


Home Prepare Request Approval Inwosce More option 
General 


5/4/2022 


MEXICO. Semel Chair. black 2 190.00 ATLANTA GA. FURNITURE 
ATLANTA Whiteboard, base 1,397.30 ATLANTA GA FURNITURE 


Thank you for ordering 


10,731.60 Total Excl. Tax (USO) 10,731.60 
0.00 Tot SD 643.90 


0 Total Inch. Tax (USD. 11,375.50 


GET 


Example GET Request URI List: 


http: //bc20-sandbox-wl- 
default:7048/BC/api/v2.0/companies ({companyID}})/salesInvoices (d943154c-54ca- 
ecl1-9617-cb648af3a4e2) /salesInvoiceLines 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesInvoices(5e7604f6-1155-ed11-8c36- 
000d3a8dc661) /salesInvoiceLines (791216fe-1255-ed11-8c36-000d3a8dc661) 
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Example GET Request URI Single (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesInvoiceLines (791216fe-1255-ed11-8c36-000d3a8dc661) 


Example GET Response (1 entity shown from a longer list): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/S$metadata#companies ({ {companyID}})/salesInvoices (5e7604f6-1155- 
ed11-8c36-000d3a8dc661) /salesInvoiceLines", 

"value": [ 

{ 
"@odata.etag": "W/\"JzE50zgzNzA2NTY50TEOMDUZNTI4MzUxOzAwOyc=\"", 
Int gto eO Gf ec 55 edie 9936-0/0/06/92819 8/66/60 
"documentId": "5e7604f6-1155-ed11-8c36-000d3a8dc661", 
"sequence": 10000, 
"itemId": "7e15971e-df3a-ed11-bbae-6045bd8e554a", 
"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1936-S", 

"description": "BERLIN Guest Chair, yellow", 
MelsyexesestoakeigeAuhg WW. 

"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


Uiminen teeta iyo te. 

Xreruexm esit yos T 

"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
WamoeumisExelucduimcnas D 

Mace occ EWBNIUBNUERBM 

WeEaxPercenit ss: Dy 

WeEOtallaxAmMounts ooko; 

"amountIncludingTax": 809.76, 
"invoiceDiscountAllocation": 0, 

"netAmount": 771.2, 

"netTaxAmount": 38.56, 

"netAmountIncludingTax": 809.76, 

"shipmentDate": "2024-10-26", 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


), 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesInvoices(5e7604f6-1155-ed11-8c36- 
000d3a8dc661) /salesInvoiceLines 


Example POST Request Body: 


"lineType": "Item", 
"lineObjectNumber": "1960-S", 
"ieqeusapdbgs/ "E 2 


PART 3: SALES 
CHAPTER 34: SALES INVOICE LINES 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesInvoices (5e7604f6-1155- 
ed11-8c36-000d3a8dc661) /salesInvoiceLines/Sentity", 

"Qodata.etag": "W/N"JzIwOzEyMTIwMTMANDY yOTA4MDkyMzYzMTswMDsnN"", 

"id": "470e29c9-1355-ed11-8c36-000d3a8dc661", 

"documentId": "5e7604f6-1155-ed11-8c36-000d3a8dc661", 

"sequence": 30000, 

"itemId": "8015971e-df3a-ed11-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1960-S", 

"description": "ROME Guest Chair, green", 

JelsisyoscalpsxEnpuo Ag UW 

"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


D üyaabipdENcahexewu B. EA te. 

WeiicWatESHES/ S e 

"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
Samounmt Exe ludimoglaxs T SS SO, 

tace occ EUETENIUBSUERBM 

WtaxPencenit m 

Docal Tax mounta: OTAS, 

"amountIncludingTax": 404.88, 
"invoiceDiscountAllocation": 0, 

"netAmount": 385.6, 

"netTaxAmount": 19.28, 

"netAmountIncludingTax": 404.88, 

"shipmentDate": "2024-10-26", 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesInvoices(5e7604f6-1155-ed11-8c36- 
000d3a8dc661) /salesInvoiceLines (470e29c9-1355-ed11-8c36-000d3a8dc661) 


Example PATCH Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesInvoiceLines (470e29c9-1355-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


JenyeWhEabibw 8 gy 
"discountPercent": 25 


Example PATCH Response: 
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{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({ {companyID}})/salesInvoiceLines/S$entity", 

"Qodata.etag": "W/N"JzE5OzU3NjE3MDk2MTIINDAINTgzOTgxOzAwOyc-N"", 

argu aues Seo) a5 ó NO 

"documentId": "5e7604f6-1155-ed11-8c36-000d3a8dc661", 

"sequence": 30000, 

"itemId": "8015971e-df3a-ed1l1-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1960-S", 

"description": "ROME Guest Chair, green", 

UigkSsereijoeieia2 e WU 

"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


rogante Ens coto aleve ty 

eiretie nena B ii, 

"di scountAmounmbt*: 58576, 

"discountPercent": 25, 

"discountAppliedBeforeTax": false, 
Wamountbexclucimgilasc |i 5 Gncd:, 

NraxCode UhUR NTU RR: U, 

NEaxXPercente sy) 5; 

"totalTaxAmount": 57.84, 

"amountIncludingTax": 1214.64, 
"invoiceDiscountAllocation": 0, 

"netAmount": 1156.8, 

"netTaxAmount": 57.84, 

"netAmountIncludingTax": 1214.64, 

"shipmentDate": "2024-10-26", 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesInvoices (5e7604£6-1155-ed11-8c36- 
000d3a8dc661) /salesInvoiceLines (470e29c9-1355-ed11-8c36-000d3a8dc661) 


Example DELETE Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID])])/salesInvoiceLines (470e29c9-1355-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 
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Unposted Sales Invoice Lines can be created manually, though the particulars of creating 
Sales Invoices are beyond this book. If the line has some information populated, it should be 
available via the API. 


UPDATING 


Adjusting any field on an unposted Sales Invoice Line, such as the Description, will update 
the line. 


DELETING 


Any unposted Sales Invoice Line may be deleted, though some business restrictions may 
prevent removal. 


Bound Actions 


No bound actions. 


e salesInvoices (page 168) 

e items (page 323) 

e accounts (page 38) 

e unitsOfMeasure (page 471) 

e itemVariants (page 339) 

e dimensionSetLines (page 427) 


| Version Changes 


22.0 Field Added: description2. 
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Chapter 35: Sales Orders 


The Sales Orders endpoint allows access to Sales Order documents. When working with 
this endpoint, it is strongly recommended to read Part 8: Chapter 88: Sales & Purchase 
Documents (page 506). 


Note: With this endpoint, a large amount of data is available, so it 
is key to consider using smart $£ilter and $select options. 
See Part 8: Chapter 89: Performance (page 511) and Part 1: 
Chapter 2: Reading / GET (page 17) for more information. 


Primary Key 


No. The numeric identifier of the Sales Order. The field is 20 characters 
and alphanumeric. 


Field Map 


API JSON: 


1 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesOrders/Sentity", 

"Qodata.etag": "W/N"JzESOzI2ODIyNTMANTkyNDE4MzgxODIxOzAwOyc-N"", 

"id": "08251e29-df3a-ed1l1-bbae-6045bd8e554a", 

number "= a sS-ORIIJQINQOOQI 

"externalDocumentNumber": "", 

"orderDate": "2024-04-02", 

"postingDate": "2024-04-02", 

"customerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 


"customerNumber": "10000", 

"customerName": "Adatum Corporation", 

"billToName": "Adatum Corporation", 

"pillToCustomerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 
"pillToCustomerNumber": "10000", 

"shipToName": "Adatum Corporation", 

"shipToContact": "Robert Townes", 

"sellToAddressLinel": "192 Market Square", 
"sellToAddressLine2": "", 

JWeredbibirexestigszU RAT lantan, 
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Is edlMumoG oun US 

"sellToStaue': "SA" 

Wrelclbartsyetexese(e eet ^a WISH) 720i 
"billToAddressLinel": "192 Market Square", 
"billToAddressLine2": "", 

Wiontibibmoeaicyy At T aM 

"Hemd dbMeyeessETV A S Mp. 

X IoISISICOIS eos c AP 

In gusTobPcosise oce oO 
"shipToAddressLinel": "192 Market Square", 
"shipToAddressLine2":; "", 

rin o OC y; a Welle”, 

Nis togomoeountec ya UM 

WshiploStatke:, AY 

Uiship MOP @siteCOcels- a WISHETI TAA 
"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "SMALL", 
"currencyId": "00000000-0000-0000-0000-000000000000", 
UcunmmeneveoccM Us Diy 

"pricesIncludeTax": false, 
"paymentTermsId": "75b14971e-df3a-edl1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
“salesperson anO 

"partialShipping": true, 
"requestedDeliveryDate": "2024-04-03", 
"discountAmount": O0, 
"discountAppliedBeforeTax": true, 

Iitecrte aulem unite Bie etur elsi gelo NET TOO 
"totalTaxAmount": 1006.06, 
NEOtralAmountelielucung Mass: sus: 
"fullyShipped": true, 


Wst aeisi MDEA EEN, 

"lastModifiedDateTime": "2024-06-03T09:55:51.632", 
"phoneNumber": "", 

"email": "robert.townes@contoso.com" 


BUSINESS CENTRAL ENTITY: 
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Customer Location Assigned Docu 


No. Sell-to Customer Name No. Code User ID Date 
S-ORD101002 10000 Adatum Corporation 5/1/ 
S-ORD101003 30000 School of Fine Art 4/22 
€ rnm1ninna4 Annan Alaina Chi Liassa 


sev [Bf Post Print/Send v ds 2 V¥ 


Amount Amount Shipped 


Document Completely Shipped Not Not Invoiced ($) Including 
Date Status Shipped Invoiced (5) Incl. Tax Amount Tax 
5/1/2022 Open No 0.00 0.00 2,285.30 242242 
4/22/2022 Open No 0.00 0.00 5,182.40 5,545.17 


rma mann we eee are ann nnn r^ An ranan 
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ü 


S-ORD101001 : Adatum Corporation 


Home Prepare Print/Send Request Approval Order Report More option 


General 
Seli-to Due Da 5/2/2022 
Nc CTO00001 Pe jnit 
Robert Townes Work Description 
A 0 
4/2/2022 
Lines Manage Une Order = 
> item 1. 1996.5 ATLANTA Whiteboard. base 12 : . PCS 
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Invoice Details 


Currency 4e Payment Sennce No payment service i$ made available 
pan 4 
T Bi 
eet Method Code 2 
ax Lia «o 4/10/2002 
ax Area Code ATLANTA GA À — 


up-to Custom Address Bill-to 

Code Name billToName 

Name shipToName Addres billToAddressLinel 

Address shipToAddressLinel Address 2 billToAddressLine2 

Address shipToAddressLine2 billToCit 
shipToCit State billToState 
shipToState ZIP Code billToPostCode 

P Code shipToPostCode untry/Region Code billToCountr 


try/Regeor shipToCountr 


9 P 
E] 
o 
i 
E 


ontact shipToContact Contact Robert Townes 


9/23/2022 


Partial 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesOrders 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesOrders (08251e29-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (1 entity shown from a longer list): 
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"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/salesOrders", 


"value": 


{ 


}, 


[ 


"Qodata.etag": "W/N"JzESOzI20DIyNTMANTkyNDE4MzgxODIxOzAwOyc-N"", 
"id": "08251e29-df3a-edl1-bbae-6045bd8e554a", 
“Vnumber Gs s oRIBN)NOON 

"externalDocumentNumber": "", 

"orderDate": "2024-04-02", 

"postingDate": "2024-04-02", 

"customerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 
"customerNumber": "10000", 

"customerName": "Adatum Corporation", 

"billToName": "Adatum Corporation", 
"pillToCustomerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 
"billToCustomerNumber": "10000", 

"shipToName": "Adatum Corporation", 

"shipToContact": "Robert Townes", 
"sellToAddressLinel": "192 Market Square", 
"sellToAddressLine2": "", 

Mereubbirexeatigsz ve SAE anea, 

sell ToCoumeay ak US 

"sellToState": "GA", 

Wis elilitoieecsincec els W SET 

"billToAddressLinel": "192 Market Square", 
"billToAddressLine2": "", 

NiosusTo euastevo Atta 

Mon dLibaMeyeiswusETEVA S MIU. 

LU oISISISOIS eic n MAP 

anb rrowsreyencierexels s - Sd anu, 

"shipToAddressLinel": "192 Market Square", 
"shipToAddressLine2":; "", 

JesatodexcariE yg UE lene 

Nisyaqomo coun er ya SM 

"shumpToSsatet UAM 

Ushiip MOPS COCgels- mnie AES 

"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "SMALL", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
Ucummemeye occ USD 

"pricesIncludeTax": false, 

"paymentTermsId": "75b14971e-df3a-edl11-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"salesperson": "JO", 

"partialShipping": true, 

"requestedDeliveryDate": "2022-04-03", 
Nisi eunte ATRIDES: MN 

"discountAppliedBeforeTax": true, 
XuisoyteasisAmecunte Bc duds giai Oo 

"totalTaxAmount": 1006.06, 

VEOralAmountelielucking Masa euo 

“ruyo ppedtus true, 

Wicheeleibisy Ue Wibheence! T 

"lastModifiedDateTime": "2024-06-03T09:55:51.632", 
"phoneNumber":; "", 

"email": "“robert.townes@contoso.com" 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]])/salesOrders 


Example POST Request Body: 


"customerNumber": "10000" 


Extra Example POST Request Body (With Sales Order Lines): 


"customerNumber": "10000" 
"salesOrderLines": [ 
{ 

"itemNumber": "1996-S", 


JenpiessnEdLiE 3 di 
), 
] 


Example POST Response (without Sales Order Lines): 


1 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/$metadatafcompanies(í((companyID])])/salesOrders/$entity", 

"Qodata.etag": "W/N"JzIwOZzEl1OTUAODI3NjUwMDUS3NjkxNzMAMTswMDsnN"", 

Ure e ada saed Ege e 00 0dBsaccdeGioily, 

Whumber "SOR DM OMO OSI, 

"externalDocumentNumber": "", 

HorderDates. "2024 -06-0S, 

oos gb aset tU 706-09 

"customerId": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 


"customerNumber": "10000", 

"customerName": "Adatum Corporation", 
"billToName": "Adatum Corporation", 
"billToCustomerId": "6c15971e-df3a-edll-bbae-6045bd8e554a", 
"billToCustomerNumber": "10000", 
"shipToName": "Adatum Corporation", 
"shipToContact": "Robert Townes", 
"sellToAddressLinel": "192 Market Square", 
"sellToAddressLine2": "", 

Meredbbirerestgs2 B. Wie Legale rei p 

Used TOCOUnery ek US. 

"sellToState": "GA", 

isenisitoPo ste oce Weal 720). 
"billToAddressLinel": "192 Market Square", 
"billToAddressLine2": "", 

Tommo ety ANT 

TomTo Conner ya. Mp. 

ToriiiTostaten UGA 

ünegiibibanodsreyencerexels US Usb OW 
"shipToAddressLinel": "192 Market Square", 
"shipToAddressLine2":; "", 

Weysaoaoxcatie y; a Ware llegas 

JeimalyeHrteXelexotat Ede ya MURS 

"shupToSudtet NGA, 
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Nishiip LOLOstCOGgels TASIE 


"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "SMALL", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"currencycode' s "USD" 


"pricesIncludeTax": false, 

"paymentTermsId": "7b14971e-df3a-ed1l1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"salesperson": "JO", 

"partialshuippuüng/ true, 

"requestedDeliveryDate": "0001-01-01", 

"discountAmount": O0, 

"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 

"totalTaxAmount": 0, 

"totalAmountIncludingTax": 0, 

"fullyShipped": false, 


UehseuEDIS YG ibis P 

"lastModifiedDateTime": "2024-06-03T09:58:09.4532", 
"phoneNumber":; "", 

"email": "robert.townes(contoso.com" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesOrders (1e1219ad-1455-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


"customerNumber": "20000" 


Example PATCH Response: 


1 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesOrders/Sentity", 

"Qodata.etag": "W/\"JzIwOzE1MDU5MzY2NTA20DI0OTIWNDgSMTswMDsn\"", 

Wicked adil eeii cles 00 0dsascdeeioity, 

Noumbper "Ss —OR Da OMG OS, 

"externalDocumentNumber": "", 

"orderDate": "2024-06-03", 


Voostingbake ss 2024 06-09) 

"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 
"customerNumber": "20000", 

"customerName"; "Trey Research", 

"billToName": "Trey Research", 

"billToCustomerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 
"billToCustomerNumber": "20000", 

"shipToName": "Trey Research", 

UshiploContact ts helen Ray, 

"sellToAddressLinel": "153 Thomas Drive", 
"sellToAddressLine2": "", 

VeredbbtexeabiEs7) CNC acO, 

Ws euni eunt OU Sd 

Ws euumositsan: e OTT 

"sellToPostCode": "61236", ) 
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"billToAddressLinel": "153 Thomas Drive", 
"billToAddressLine2": "", 

Wen Cev vs VEIE CO 

TOMTO COUNEE Va MOS" 

Wim IIvkosiecice METTI 

ous TePosiseocden a2 Sion, 

"shipToAddressLinel": "153 Thomas Drive", 
"shipToAddressLine2":; "", 

oimai HOCE ANE Wielg ego 

Misano conner ya UM 

PSPrl statene A, 

Ushi Pp UOPOsteodel Mo So 

"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
UcunsmenmeweoccM S USIDM 

"pricesIncludeTax": false, 

"paymentTermsId": "7914971e-df3a-edl1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
“salesperson MS 

"partialShipping": true, 

"requestedDeliveryDate": "0001-01-01", 
ViGhi@secoumeAMoumitety: (0) 

"discountAppliedBeforeTax": false, 
irtcoyteaslsAmm ante Boca elim elio NP 

"totalTaxAmount": 0, 

"totalAmountIncludingTax": 0, 

"fullyShipped": false, 


Wishecherbisy ss MDC aset 

"lastModifiedDateTime": "2024-06-03T10:00:42.5132", 
"phoneNumber"; "", 

"email": "helen.ray@contoso.com" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrders(1e1219ad-1455-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


From the Sales Orders list, click on the New button in the Action Bar. 
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Sales Orders: All v J Search + New li] Delete Process v [2 Release v (ait Post... Print/Send v Orc 


Sell-to External Amount 
Customer Document Location Assigned Document Completely Shipped Not 
No. 1 No. Sell-to Customer Name No. Code User ID Date Status Shipped Invoiced ($) 
S-ORD101001 : 10000 Adatum Corporation 4/2/2022 Open 0.00 
S-ORD101002 10000 Adatum Corporation 5/1/2022 Open 
S-ORD101003 30000 School of Fine Art 4/22/2022 Open 
S-ORD101004 40000 Alpine Ski House 5/13/2022 Open 


S-ORD101005 20000 Trey Research 10/26/2022 Open 


This will open a blank Sales Order card. Select a Customer, which should automatically 
assign a Sales Order No. 


Sales Order 


Home Prepare Print/Send Request Approval Order Report Actions Related Automate Fewer options 


[Gf Post... | v [È Release | ~ fi» Create Warehouse Shipment È Create Inventory Put-away/Pick... "El Archive Document 
General 


Show more 


Customer Name ee Due Date 


Contact Requested Delivery Date 
Posting Date External Document No. 


Order Date Status 


Manage Line Order Fewer options 


Item 


Reference Qty. to Assemble Unit of 
No. Description Location Code Quantity to Order Reserved Quantity Measure Code 


Filling out a Sales Order is beyond the scope of this book, but this method creates it 
enough to be available for the API. 


UPDATING 


Change a field in the General section, such as the Due Date. 


DELETING 


An unposted Sales Order can simply be deleted via the Delete action in the Action Bar. If 
it has been posted partially (shipped, invoiced, etc), it might not be possible to delete the Sales 
Order in progress. 
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Bound Actions 


e shipAndInvoice 


e customers (page 110) 

e countryRegion (page 402) 

e currencies (page 407) 

e paymentTerms (page 445) 

e shipmentMethods (page 457) 
e salesOrderLines (page 195) 

e attachments (page 378) 

e dimensionSetLines (page 427) 


Changes 


Removed an enforcement mechanism that ensured the Customer information 
matched against Customer Templates. 

Added Dimension fields to the API. 

Prices Including VAT were added. 
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Chapter 36: Sales Order Lines 


The Sales Order Lines endpoint allows access to Sales Order Lines. When working with 
this endpoint, it is strongly recommended to read Part 8: Chapter 88: Sales & Purchase 
Documents (page 506). 


Primary Key 


Document Id The generated identifier for the Sales Order Line. The field is a GUID. It 
is locked and managed by BC. 

Line No. The numeric identifier for the specific Sales Order line. It is unique only 
in the given Sales Order. Integer Identifier. 


Note that this is an aggregate table, so it often comes from a Document Line table with 
a primary key of Document No. and Line No., but the aggregate table uses the Document Id 
to ensure uniqueness. 


Field Map 


API JSON: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /salesOrders (1e1219ad-1455- 
ed11-8c36-000d3a8dc661) /salesOrderLines/Sentity", 

"Qodata.etag": "W/N"JzE5OzkxNzc20TYONDII1MjIzMDMS5NTgxOzAwOyc-N"", 

Ug a5 Sss edie MNO aede cE a 

"documentId": "1el219ad-1455-ed11-8c36-000d3a8dc661", 

"sequence": 10000, 

"itemId": "7715971e-df3a-ed1l1-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 

"description"; "PARTS Guest Chair, black", 

Meleag WW. 

"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


Wreicioneaiesy M B vir 

muni ePr recet Xo ID 

vdiscouncAmount A: 07 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 

"amountExei'udüngTase yl ) 
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NraxCode ts VhURNTLURE DU, 

MEaxPenGemitmu st 5, 

"rota lTaxAmount 2936 2107, 

vomount Ineludingrax 89096, 
"invoiceDiscountAllocation": 0, 

"netAmount": 771.2, 

"netTaxAmount": 38.56, 

"netAmountIncludingTax": 809.76, 

"shipmentDate": "2024-05-26", 

"shippedQuantity": 0, 

"invoicedQuantity": O0, 

"invoiceQuantity": 4, 

Wohin Gwequisd tyi a 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


BUSINESS CENTRAL ENTITY: 


S-ORD101001 - Adatum Corporation 


Home Prepare Print/Send Request Approval Order Report 


General 


Adatum Corporation Due Date 5/2/2022 


4/3/2022 


ATLANTA Whiteboard. base 1.39730 ATLANTA 
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Lines 


ATLANTA.GA FURNITURE 16.767.60 17,773.66 


Lines Manage 


4/3/2022 4/3/2022 4/3/2022 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrders(1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /salesOrderLines 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrders(1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /salesOrderLines (76599c81-1555-ed11-8c36-000d3a8dc661) 


Example GET Response (1 entity shown from a longer list): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/$metadatafcompanies (((companyID]))/salesOrders(1e1219ad-1455- 
ed11-8c36-000d3a8dc661) /salesOrderLines", 

ava M e E 

1 
"Qodata.etag": "W/N"JzE5OzkxNzc20TYONDII1MjIzMDM5NTgxOzAwOyc-N"", 
"id": "76599c81-1555-ed11-8c36-000d3a8dc661", 
"documentId": "1e1219ad-1455-ed11-8c36-000d3a8dc661", 
"sequence": 10000, 
"itemId": "7715971e-df3a-ed11-bbae-6045bd8e554a", 
"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 
"description “PARIS GUest Chair, black, 
JelexsosalgsiEni egg WW 


PART 3: SALES 
CHAPTER 36: SALES ORDER LINES 


"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 

Wigibiciaiziney Ye A, 

vani cEricet: 71922787 

uenis countAmoun ts: (0), 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
Vamounthxcludinglax 2. (7l2, 

Hrane odete ERE UR NTE URIs, 

"taxPercent": 5, 

WeOtallaxAmountl’: 3872967 

"amountIncludingTax": 809.76, 
"invoiceDiscountAllocation": 0, 

"netAmount": 771.2, 

"netTaxAmount": 38.56, 

"netAmountIncludingTax": 809.76, 

"shipmentDate": "2024-05-26", 

"shippedQuantity": 0, 

"invoicedQuantity": O0, 

"invoiceQuantity": 4, 

“Shi pouantieys Ar 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


), 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrders(1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /salesOrderLines 


Example POST Request Body: 


"lineType": "Item", 
"lineObjectNumber": "2000-S", 
Ue wiemibihey Ys 12 


Example POST Response: 


1 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadatadscompanies(((companyID])))/salesOrders(1e1219ad-1455- 
ed11-8c36-000d3a8dc661) /salesOrderLines/Sentity", 

"Qodata.etag": "W/\"JzE50z0xMjgwNTc3Mzk1MzE4MDM3MzkxOzAwOyc=\"", 

"id": "6976d902-1655-ed11-8c36-000d3a8dc661", 

"documentId": "1el1219ad-1455-ed11-8c36-000d3a8dc661", 

"sequence": 40000, 

"itemId": "8915971e-df3a-edl1-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chair, green", 
"oleexesealgoedleugua dg. UE 

"unitOfMeasureId": "e415971e-df3a-edl1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


ouant eye d. 
unie Pricen Joc 
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"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 

Vigiio minicar elkuichineWerd PD 

iutzasce oce EVE ENIIDUEEB 

WeEaxPercenit: 5, 

"totalTaxAmount": 114.06, 

“amount ineludingtaxt 2 SIS 216), 
"invoiceDiscountAllocation": 0, 

"netAmount": 2281.2, 

"netTaxAmount": 114.06, 

"netAmountIncludingTax": 2395.26, 

"shipmentDate": "2024-05-26", 

"shippedQuantity": 0, 

vinvorcedouantiey a: Oly 

"invoiceQuantity": 12, 

J'sigugsYoIEegotES EN S did 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrders(1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /salesOrderLines (6976d902-1655-ed11-8c36-000d3a8dc661) 


Example PATCH Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrderLines(6976d902-1655-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


"iembiesauEdbies; Ye ie, 
"discountPercent": 20 


Example PATCH Response: 


1 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesOrderLines/Sentity", 

"Qodata.etag": "W/N"JzE5Ozc2MzMwMjc2MDMANDYS5MDYOODkxOzAwOyc-N"", 

"id": "6976d902-1655-ed11-8c36-000d3a8dc661", 

"documentId": "1e1219ad-1455-ed11-8c36-000d3a8dc661", 

"sequence": 40000, 

"itemId": "8915971e-df3a-ed11-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chair, green", 
WiclSsiorealioieaverd2 S WW. 

"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


Jeniewadbdlips7 B 0204 
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"unditErPqceU o0" 

"discountAmount": 456.24, 

"discountPercent": 20, 

"discountAppliedBeforeTax": false, 
Wamounehxeludameg Pas. 9249/67 

"taxCode": "FURNITURE", 

NraxPercemt: re 

"totalTaxAmount": 917.25, 

Vamount ine luding kat IN) 221k 5 
"invoiceDiscountAllocation": 0, 

"netAmount": 1824.96, 

WnetLaxAmountes: 9257 

"netAmountIncludingTax": 1916.21, 

"shipmentDate": "2024-05-26", 

"shippedQuantity": 0, 

"invoicedQuantity": 0, 

MUMViGHk Ge 9 uam ele 

LisinajoOuieincmiey S: iLZ 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/salesOrders (1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /salesOrderLines (6976d902-1655-ed11-8c36-000d3a8dc661) 


Example DELETE Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesOrderLines (6976d902-1655-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


Sales Order Lines can be created manually, though the particulars of creating Sales Orders 
are beyond the scope of this book. If the line has some information populated, it should be 
available via the API. 


UPDATING 


Adjusting any field on an unposted Sales Order Line, such as the Description, will update 
the line. 
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DELETING 


Any unposted Sales Order Line may be deleted, though some business restrictions may 
prevent removal. If it has been posted partially (shipped, invoiced, etc.), it might not be possible 
to delete the Sales Order Line in progress. 


Bound Actions 


No bound actions. 


Navigations 


e salesOrders (page 184) 

e items (page 323) 

e accounts (page 38) 

e unitsOfMeasure (page 471) 

e itemVariants (page 339) 

e dimensionSetLines (page 427) 
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Chapter 37: Sales Quotes 


The Sales Quotes endpoint allows access to Sales Quote documents. When working with 
this endpoint, it is strongly recommended to read Part 8: Chapter 88: Sales & Purchase 
Documents (page 506). 


Primary Key 


No. The numeric identifier of the Sales Quote. The field is 20 characters 
and alphanumeric. 


Field Map 


API JsoN: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/S$metadata#companies ({ {companyID}})/salesQuotes/Sentity", 
"Qodata.etag": "W/N"JzES5OzE3MzAOODMzNTMwMTgyMTYA4OTkxOzAwOyc-N"", 
"id": "04251e29-df3a-edl1-bbae-6045bd8e554a", 


VhewbWdexessl E PASI-IOJOKOHE((0 ILM 
"externalDocumentNumber": "", 
"documentDate": "2024-04-02", 


"postingDate": "2024-04-02", 
"dueDate": "2024-04-16", 
"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 


"customerNumber": "20000", 
"customerName": "Trey Research", 
"billToName": "Trey Research", 
"billToCustomerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 
"billToCustomerNumber": "20000", 
"shipToName": "Trey Research", 
"shipToContact": "Helen Ray", 
"sellToAddressLinel": "153 Thomas Drive", 
"sellToAddressLine2": "", 

deredblbuneXebuES Ma EMC agon, 

Ws cle Comme n MAUS C 

VsedsmseEeEGUg UE, 

UseliloPostCodels: 6d 2960 
"pillToAddressLinel": "153 Thomas Drive", 
"billToAddressLine2": "", 

VissribWameyeatiEy; WCO N 

TEENDO C ONNEEN s. USA 

IO SMIMINTIO rts c A 
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UbiiePostCodel anol 2 S Sr 

"shipToAddressLinel": "153 Thomas Drive", 
"shipToAddressLine2"; "", 

VeimatoHrtolestiev; S. Melaatiexeie t9" 

Bis tuagomo eom ya ME SM 

"shipo states. MITT 

Ushio OP Ost Codey oloon 

"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
Ucummemeye occ WOKS ID 

"paymentTermsId": "7914971e-df3a-edll-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"salesperson": "JO", 

"discountAmount": 0, 

"totalAmountExcludingTax": 1928, 

"totalTaxAmount": 96.4, 
"totalAmountIncludingTax": 2024.4, 


mstatili Wipheenee4! 

sentiat OO OE OT OI TS 

Wrs elime Deco EIOS ONES INTUS 

I accepiesiatet O07. OO 
"lastModifiedDateTime": "2024-06-03T10:20:40.0332", 
"phoneNumber":; "", 

"email": "helen.ray@contoso.com" 


BUSINESS CENTRAL ENTITY: 
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Sales Quot e e T ioi cs 


S-QUO!1001 : Trey Research 


Home Prepare Print/Send Request Approval Quote More options 
General 

Sell-to Quote Valid To Date 
Contact No CT000003 Responsibility Center 
Phone No phoneNumber Assigned User IC 


u 
ct 
m 
cr 
E 
I6] 


email Work Description 
Contact shipToContact 
Customer Ter e 
Lines Manage Line Functions Fewer options 2 & 
tem Reference Qty. to Assemble Unit of Unit Price £x 
Type No No Description Location Code Quante to Order Measure Code Tax 
> item + 19365 BERLIN Guest Chair. yellow 10 0 PCS 192.80 


Subtotal Excl. Tax (USD) 1,928.00 Total Excl. Tax (USD) totalAmountExcludingTax 
Inv. Discount Amount Excl. Tax ( discountAmount Total Tax (USD) totalTaxAmount 
im cunt % 0 Total Incl. Tax (USD) totalAmountIncludingTax 
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Invoice Details Show less 


currencyCode 


billToName 


shipToName Address billToAddressLinel 


shipToAddressLinel Address 2 billToAddressLine2 


shipToAddressLine2 City billToCit 
shipToCit 
shipToState 
shipToPostCode 


shipToCountr 


Fa] 
S 
3 
E 
a 
$ 


shipToContact 


w 
IÍ 
N 
wg 
< 
" 
o 
í 

o 


Shipment Date 2 


Shipment Method 
Code 

Agent 

Agent service 


Package Tracking No 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesQuotes 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesQuotes (04251e29-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (1 entity shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesQuotes", 
"value": [ 


{ 


"Qodata.etag": "W/N"JzE5OzE3MzAOODMzNTMwMTgyMTY4OTkxOzAwOyc-N"", 
"id": "04251e29-df3a-edll-bbae-6045bd8e554a", 
"hoppygalexexe Mg. WS XOU OIL 
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"externalDocumentNumber": "", 

"documentDate": "2024-04-02", 

"postingDate": "2024-04-02", 

"dueDate": "2024-04-16", 

"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 
"customerNumber": "20000", 

"customerName": "Trey Research", 

"billToName": "Trey Research", 

"billToCustomerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 
"billToCustomerNumber": "20000", 

"shipToName": "Trey Research", 

"shipToContact": "Helen Ray", 

"sellToAddressLinel": "153 Thomas Drive", 
"sellToAddressLine2": "", 
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"pillToAddressLinel1": "153 Thomas Drive", 
"billToAddressLine2": "", 
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"shipToAddressLinel": "153 Thomas Drive", 
"shipToAddressLine2": "", 
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UshuplOoPostCodels: 612 316, 

"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
WeurrencyCode™: "USD" 

"paymentTermsId": "7914971e-df3a-ed1l1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
WsalesperSOum o 
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"totalAmountExcludingTax": 1928, 

"totalTaxAmount": 96.4, 

"totalAmountIncludingTax": 2024.4, 


Uem B a Drane 

"sentDate": "0001-01-01T00:00:002", 

tyo lmaumen imate e OO.) V, 

"acceptedDate": "0001-01-01", 
"lastModifiedDateTime": "2024-06-03T10:20:40.0332", 
"phoneNumber"; "", 

"email": "helen.ray(8contoso.com" 


}, 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesQuotes 


Example POST Request Body: 


"customerNumber": "20000", 
"postingDate": "2024-05-04" 
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Example POST Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesQuotes/Sentity", 
"@odata.etag": "W/\"JzE50zgzMzUyNTAyMDkzMjg0OTY30DMxOzAwOyc=\"", 
"id": "16eaaa41-1855-ed11-8c36-000d3a8dc661", 
Lobes m. Uto) SU 


"externalDocumentNumber": "", 
"documentDate": "2024-10-26", 
"postingDate": "2024-05-04", 

"dueDate": "2024-11-09", 

"customerId": "6d15971e-df3a-edll-bbae-6045bd8e554a", 
"customerNumber": "20000", 
"customerName": "Trey Research", 
"billToName": "Trey Research", 
"pillToCustomerId": "6d15971e-df3a-ed11-bbae-6045bd8e554a", 
"billToCustomerNumber": "20000", 
"shipToName": "Trey Research", 
"shipToContact": "Helen Ray", 
"sellToAddressLinel": "153 Thomas Drive", 
"sellToAddressLine2": "", 

Weyxeabibatoestigy Us. Mielaatierxsieto 
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"sellToStauet*: "TM 

"sellToPostCode": "61236", 
"billToAddressLinel": "153 Thomas Drive", 
"billToAddressLine2": "", 
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"Vignidllbareyerexsneterexel2 ys WIS SIM 
"shipToAddressLinel": "153 Thomas Drive", 
"shipToAddressLine2": "", 

Veit 8 "else eo, 
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oship lostatetk HLE, 

UshiploPostCodels.. 612316, 
"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "MEDIUM", 
"currencyId": "00000000-0000-0000-0000-000000000000", 
"currencyCode": "USD", 


"paymentTermsId": "7914971e-df3a-edl11-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"salesperson": "JO", 

NemscoumeAmounitt:) 107 
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"totalTaxAmount": 07 
"totalAmountIncludingTax": 0, 


Uem B: Vibrecune 
"sentDate": "0001-01-01T00:00:002", 
Val TOUmtal Datel: OO OE e 
"acceptedDate": "0001-01-01", 
"lastModifiedDateTime": "2024-06-03T10:23:44.122", 
"phoneNumber"; "", 
"email": "helen.ray@contoso.com" 
} 
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PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesQuotes (16eaaa41-1855-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


"customerNumber": "30000", 
"dueDate": "2024-11-30" 


Example PATCH Response: 


{ 
"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesQuotes/Sentity", 
"@odata.etag": "W/N"JzIWOzE3ODEzNjUINDMONTQSNTYzMTcyMTswMDsnN"", 
"id": "16eaaa41-1855-ed11-8c36-000d3a8dc661", 
“mumos ra SONOS 


"externalDocumentNumber": 


"wn 
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"documentDate": 
"postingDate": 


"2024-10-26", 
"2024-05-04", 


"dueDate": "2024-11-30", 
"customerId": "6e15971e-df3a- 
"customerNumber": "30000", 
"customerName": "School of Fine Art", 
"billToName": "School of Fine Art", 
"billToCustomerId": "6e15971e-df3a- 
"billToCustomerNumber": "30000", 
"shipToName": "School of Fine Art", 
"shipToContact": "Meagan Bond", 
llToAddressLinel": "10 High Tower Green", 
llToAddressLine2": "", 

sellToCity": "Miami", 

sed TOCOuUntEey USI, 

selilTosStake™s Writ, 
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dll1-bbae-6045bd8e554a", 


dll1-bbae-6045bd8e554a", 


"billToAddressLinel": "10 High Tower Green", 
"billToAddressLine2": "", 
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"shipToAddressLinel": "10 High Tower Green", 
"shipToAddressLine2"; "", 
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"shortcutDimensionlCode": "SALES", 
"shortcutDimension2Code": "LARGE", 

"currencyId": "00000000-0000-0000-0000-000000000000", 


Ucummemeye occ Ucn 

"paymentTermsId": "8114971e-df3a-edll1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
"salesperson": “JOIN, 

"discountAmount": O0, 

"totalAmountExcludingTax": 0, 

WeOrallaxAmounte: Ol, 

toca Amoune me ucingan: IO" 
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"sentDate": "0001-01-01T00:00:002", 
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"acceptedDate": "0001-01-01", 
"lastModifiedDateTime": "2024-06-03T10:26:35.652", 
"phoneNumber"; "", 

"email": "meagan.bond@contoso.com" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/salesQuotes (16eaaa41-1855-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


From the Sales Quotes list, click on the New button in the Action Bar. 


Sales Quotes: All v | J Search + New lJ Delete Process ^^ [2 Release Vv Print/Send v Quote v 


External 
Sell-to Document 
No. t Customer No. Sell-to Customer Name No. Sell-to Contact Posting Date 


S-QUO1001 .: 20000 Trey Research Helen Ray 4/2/2022 
S-QUO1002 40000 Alpine Ski House lan Deberry 4/3/2022 


S-QUO1003 30000 School of Fine Art Meagan Bond 5/4/2022 


This will open a blank Sales Quote card. Select a Customer, which should automatically 
assign a Sales Quote No. 
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Sales Quote 


Home Prepare — Print/Send Request Approval Quote More options 


&) Make e =) Make e [Release v ‘Archive Document 


General Show more 


Customer Name Rm Due Date 
External Document No. Requested Delivery Date 


Contact Status 


Manage Line Functions Fewer options 
Item Qty. to Unit of Tax 
Reference Location Assemble to Measure Unit Price Area Tax Group 


No. Description Code Quantity Order Code Excl. Tax Code Code 


0 


Filling out a Sales Quote is beyond the scope of this book, but this method creates it 
enough to be available for the API. 


UPDATING 


Change a field in the General section, such as the Due Date. 


DELETING 


An unposted Sales Quote can simply be deleted via the Delete action in the Action Bar. 
If it has been posted partially (shipped, invoiced, etc.), it might not be possible to delete the 
Sales Quote in progress. 


Bound Actions 


e makelnvoice 
e makeOrder 
e send 


e customers (page 110) 

e countryRegion (page 402) 

e currencies (page 407) 

e paymentTerms (page 445) 

e shipmentMethods (page 457) 
e salesQuoteLines (page 212) 
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e pdfDocument (page 450) 
e attachments (page 378) 
e dimensionSetLines (page 427) 


Version Changes 


Removed an enforcement mechanism that ensured the Customer information 


matched against Customer Templates 
Added Dimension fields to the API 
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Chapter 38: Sales Quote Lines 


The Sales Quote Lines endpoint allows access to Sales Quote Lines. When working with 
this endpoint, it is strongly recommended to read Part 8: Chapter 88: Sales & Purchase 
Documents (page 506). 


Primary Key 


Document Id The generated identifier for the Sales Quote Line. It is created and used 
under the hood by Business Central to perfectly separate and identify. 
The field is a GUID. It is locked and managed by BC. 
Line No. The numeric identifier for the specific Sales Quote Line. It is unique only 
in the given Sales Quote. Integer Identifier. 

Note that this is an aggregate table, so this often comes from a Document Line table with 
a primary key of Document No. and Line No., but the aggregate table uses the Document Id 
to ensure uniqueness. 


Field Map 


API JSON: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /salesQuotes (16eaaa41-1855- 
ed11-8c36-000d3a8dc661) /salesQuoteLines/Sentity", 

"Qodata.etag": "W/N"JzE5Ozg5ODAONzUG3NTM3NjOwNzIWNjcxOzAwOyc-N"", 

"id": "9bbc49f3-1855-ed11-8c36-000d3a8dc661", 

"documentId": "16eaaa41-1855-ed11-8c36-000d3a8dc661", 

"sequence": 10000, 

"itemId": "8915971e-df3a-ed11-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chair, green", 
"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


tuni tEricet: 90715 
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"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
"amountExceludungrTrax'": 190, 

"taxCode": "FURNITURE", 

"LtaxPercent": 7, 

Winovciwteriopimes OBOT 

vamount Ineludingrax 20341077 

"netAmount": 1901, 

"netTaxAmount": 133.07, 

"netAmountIncludingTax": 2034.07, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


BUSINESS CENTRAL ENTITY: 


Sa 


S-QUO1001 : Trey Research 


Home Prepare Print/Send Request Approval Quote 
General 


Trey Research Due Date 


Code 


BERLIN Guest Chaic yellow ) P 192.80  CHICA.. FURNITU. 


2.02440 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/salesQuotes (16eaaa41-1855-ed11-8c36- 
000d3a8dc661) /salesQuoteLines 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/salesQuotes (16eaaa41-1855-ed11-8c36- 
000d3a8dc661) /salesQuoteLines (9bbc49f3-1855-ed11-8c36-000d3a8dc661) 


Example GET Response (2 entities shown from a longer list): 
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"@odata.context": 


ed11-8c36-000d3a8dc661) /salesQuoteLines", 


"value": 


{ 


[ 


"Qodata.etag": "W/\"JzE50zg50DA0NzZU3NTM3NjQwNzIwNjcxOzAwOyc=\"", 


Wig Ob be4 Sts te5bedisi99]5356-090/03989d6c6/061» 
"documentId": "16eaaa41-1855-ed11-8c36-000d3a8dc661", 
"sequence": 10000, 

"itemId": "8915971e-df3a-edl1-bbae-6045bd8e554a", 
"accountId": "00000000-0000-0000-0000-000000000000", 
"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chair, green", 
"unitOfMeasureId": "e415971e-df3a-edl1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 

Mhoyoubigleseaersu m ICG. dL 
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"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
"amountExcludingTax": 1901, 

intrasse ode = “UR URINITMELUIRIR, Ur 

"taxPercent": 7, 

NitotalTaxAmount'™: 133.077 

"amountIncludingTax": 2034.07, 

"netAmount": 1901, 

"netTaxAmount": 133.07, 

"netAmountIncludingTax": 2034.07, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


"Qodata.etag": "W/N"JzE5OzMxNTg1ODAxMTQwMzIA4NzcONTExOzAwOyc-N"", 


Udo edo oss edie geo Nod aede 6/9199 
"documentId": "16eaaa41-1855-ed11-8c36-000d3a8dc661", 
"sequence": 20000, 

"itemId": "7715971e-df3a-edl11-bbae-6045bd8e554a", 
"accountId": "00000000-0000-0000-0000-000000000000", 
"lineType": "Item", 

"lineObjectNumber": "1900-S", 

cle sic eto nt MU PARITSGUesi Clau ratur 
"unitOfMeasureId": "e415971e-df3a-edl1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 

Muni Prieels 192118, 

ouant teya &), 

uois countAmounts: (0) 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
"amountExcludingTax": 964, 

WiEaxCocel i) bh URN WRI, 

"taxPercent": 7, 

"totalTaxAmount": 67.48, 

"amountIncludingTax": 1031.48, 

"netAmount": 964, 

"netTaxAmount": 67.48, 

"netAmountIncludingTax": 1031.48, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


PART 3: SALES PAGE 
CHAPTER 38: SALES QUOTE LINES 


"https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /salesQuotes (16eaaa41-1855- 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesQuotes (16eaaa41-1855-ed11-8c36- 
000d3a8dc661) /salesQuoteLines 


Example POST Request Body: 


"lineType": "Item", 
"lineObjectNumber": "2000-S", 
Wie(iciniciliey Ys 20), 
"discountAmount": 10 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesQuotes (16eaaa41-1855- 
ed11-8c36-000d3a8dc661) /salesQuoteLines/Sentity", 

"Qodata.etag": "W/\"JzE50zY40TAIMzgxODgxNjJAxNzY1ODExOzAwOyc=\"", 

Waele Wier sills Sey il Les GOO OclsatrcleGooil 7 

"documentId": "16eaaa41-1855-ed11-8c36-000d3a8dc661", 

"sequence": 30000, 

"itemId": "8915971e-df3a-ed11-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chair, green", 
"unitOfMeasureId": "e415971e-df3a-edll1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


Wumeadt: Preece 19011, 
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"discountPercent": 0.26302, 
"discountAppliedBeforeTax": false, 
"amountExcludingTax": 3792, 

"taxCode": "FURNITURE", 

uraxPercent H: Tr 

"totalTaxAmount": 265.44, 

"amountIncludingTax": 4057.44, 

"netAmount": 3792, 

"netTaxAmount": 265.44, 

"netAmountIncludingTax": 4057.44, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


PART 3: SALES 
CHAPTER 38: SALES QUOTE LINES 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesQuotes (16eaaa41-1855-ed11-8c36- 
000d3a8dc661) /salesQuoteLines (1961fb51-1955-ed11-8c36-000d3a8dc661) 


Example PATCH Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesQuoteLines (1961f£b51-1955-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


“eame eya SiO), 
"discountAmount": 15 


Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /salesQuotes (16eaaa41-1855- 
ed11-8c36-000d3a8dc661) /salesQuoteLines/Sentity", 

"Qodata.etag": "W/N"JzE5OzMwMjAzMTO2MjYyMzcwOTgzMTExOzAwOyc-N"", 

Wiel a Vil Selo sili O5) Seyler so= OO OclseisicleG Gil M» 

"documentId": "16eaaa41-1855-ed11-8c36-000d3a8dc661", 

"sequence": 30000, 

"itemId": "8915971e-df3a-ed11-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chair, green", 
"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


Vundit Prices) 190,17 

JeuewdEaLipw/ Mg SO), 

"discountAmount": 15, 
WeiscounerPencent! m 0263027 
"discountAppliedBeforeTax": false, 
"amountExcludingTax": 5688, 
I"taxcodem “FURNITURE, 
"taxPercent": 7, 
Iotcorteasieiia Amount: 0998567 

"amountIncludingTax": 6086.16, 

"netAmount": 5688, 

ine aseAmounu- 399 67 

"netAmountIncludingTax": 6086.16, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/salesQuotes (16eaaa41-1855-ed11-8c36- 
000d3a8dc661) /salesQuoteLines (1961fb51-1955-ed11-8c36-000d3a8dc661) 


Example DELETE Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /salesQuoteLines (1961f£b51-1955-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


Sales Quote Lines can be created manually, though the particulars of creating Sales 
Quotes are beyond this book. If the line has some information populated, it should be available 
via the API. 


UPDATING 


Adjusting any field on a Sales Quote Line, such as the Description, will update the line. 


DELETING 


Any Sales Quote Line may be deleted, though some business restrictions may prevent 
removal. 


Bound Actions 


No bound actions. 


e salesQuotes (page 202) 

e items (page 323) 

e accounts (page 38) 

e unitsOfMeasure (page 471) 

e itemVariants (page 339) 

e dimensionSetLines (page 427) 
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| Version Changes 


18.1 Added Location. 
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Chapter 39: Sales Shipments 


Unlike other Sales Document endpoints, the Sales Shipments endpoint points exclusively 
to the Posted Sales Shipments in Business Central, as there is not an unposted form. 


This also means it does not rely on any aggregate mechanisms. 


Note: With this endpoint, a large amount of data is available, so it 
is key to consider using smart $£ilter and $select options. 
See Part 8: Chapter 89: Performance (page 511) and Part 1: 
Chapter 2: Reading / GET (page 17) for more information. 


Primary Key 


No. The identifier of the Sales Shipment. The field is 20 characters and 
alphanumeric. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/salesShipments/Sentity", 

"@odata.etag": "W/N"JzIwOzEwMjUINzMOMDQzMzU2MTCS5NDMzMTswMDsnN"", 

"id": "2a84d8353-df3a-edll-bbae-6045bd8e554a", 

numos ra Sc SEPTA 

"externalDocumentNumber": "", 

Nimvyioweebatce +. 2029-0 5] 
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"customerPurchaseOrderReference"; "", 

"customerNumber": "20000", 

"customerName": "Trey Research", 

"billToName": "Trey Research", 

"billToCustomerID": "20000", 

"shipToName": "Trey Research", 

"shipToContact": "Helen Ray", 

"sellToAddressLinel": "153 Thomas Drive", 

"sellToAddressLine2": "", 
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DO Cantey Ug 


" 


WGhakeacge@ne, 


SITO Gomes ya JUSS, 
Lieu S UB 
sellToPostCode": "61236", 


"pillToAddressLinel": "153 Thomas Drive", 
"pillToAddressLine2": "", 


Mop db reyes g 


NiGhatcagone, 


Went Iibteceuimeeys "aUe. 
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Shiplo Ga tyun: 


" 


shipToAddressLinel": "153 Thomas Drive", 
shipToAddressLine2": 


wo 
, 


ene ao 
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"curbrencycodeu USDI 

"orderNumber": "", 

"paymentTermsCode": "COD", 

"shipmentMethodCode": "", 

"salesperson": "JO", 

"pricesIncludeTax": false, 

"lastModifiedDateTime": "2024-04-17T01:30:38.162", 


"phoneNumber": 


wie 
t 


"email": "helen.ray@contoso.com" 


Note: billToCustomerlD was called billToCustomerNumber in older 
versions, and for. This is also a rare case where an ID is referring to 
a BC user editable value, not the systemID of a related field. This is 
talked about in Part 8:Chapter 91: API Bugs (517) 
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CHAPTER 39: SALES SHIPMENTS 


BUSINESS CENTRAL ENTITY: 


Home Shipment Certificate of Supply More options 


General 


No. number Contact shipToContact 


Customer customerName No. Printed 
Posting Date postingDate 
Document Date invoiceDate 


Requested Delivery Date 


Sell-to 
Address 
Address 2 


sellToCit 


Promised Delivery Date 


sellToState 


Quote No. 


sellToPostCode Order No 


t| |u 
m||m 
H| |H 
H| |H 
SS 
Dy) I» 
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a} lo 
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uj |u 
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Country/Region sellToCountr External Document No 


Contact No CTO000005 Salesperson Code salesperson 


Phone No. phoneNumber Responsibility Center 


Mobile Phone No. Work Description 


Email 


Shipping 


Addres Location Code 


Name shipToName Outbound Whse. Handli. 
Address Shipping Time 
Address 2 ipToAddressLine2 Shipment Method 

oy shiproCit Code 
State shipToState Agent 

ZIP Code shipToPostCode Agent Service 

Country/Region shipToCountr Package Tracking No 


Contact shipToContact Shipment Date 9/23/2022 


Billing 


Customer No. Contact No 
Name billToName Phone No. 
Address Mobile Phone No. 

Email schoolLof.fine.art@contoso.com 
billToCit Contact Meagan Bond 
billToState Department Code SALES 


Customergroup Code LARGE 


shipToAddressLinel 
billToAddressLinel 
billToAddressLine2 
billToPostCode 


Country/Region Code billToCountr 
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GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesShipments 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesShipments (2a8d8353-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (1 entity shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesShipments", 
"value": [ 


{ 
"@odata.etag": "W/N"JzIwOzEwMjUINzMOMDQzMzU2MTCS5NDMzMTswMDsnN"", 
"id": "2a8d8353-df3a-edll-bbae-6045bd8e554a", 
mumos rur Usa) 2(]0)1:0)- 
"externalDocumentNumber": "", 
vinvoncepaten 240 st 
JMieYoyetigsue ele B 29220 Onc 7) 7 
"dueDate": "2024-01-17", 
"customerPurchaseOrderReference": "", 
"customerNumber": "20000", 
"customerName"; "Trey Research", 
"billToName": "Trey Research", 
Moa IMO iuste ense rp e MUNDI) 
"shipToName": "Trey Research", 
"shipToContact": "Helen Ray", 
"sellToAddressLinel": "153 Thomas Drive", 
"sellToAddressLine2": "", 
JeyedbbuoestiEs s WielaatexXer9 
pse llToCountry e: US 
Used ToStbatuc TUM 
"sellToPostCode": "61236", 
"billToAddressLinel": "153 Thomas Drive", 
"billToAddressLine2": "", 
Wie pl TblbateXe bie a WClaaierereoi m, 
Wen JiMveciouininey ys RIT UN 
Us opk Ib ikubleysiecheeY 4 ATTEN 
HosLbinoriosiCece ls WO SW. 
"shipToAddressLinel": "153 Thomas Drive", 
"shipToAddressLine2": "", 
Wigimaotoewiny ys Medatatexs eto, 
isis COMET ya MOIST, 
oship lo grated aT 
UshaploPost@odes: 2 612306" 
Neunnencyicode ls) “USDE, 
"orderNumber": "", 
"paymentTermsCode": "COD", 
"shipmentMethodCode": "", 
"salesperson": "JO", 
"pricesIncludeTax": false, 
"lastModifiedDateTime": "2024-04-17T01:30:38.162", 
"phoneNumber":; "", 
"email": "helen.ray@contoso.com" 


}, 
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CRUD Steps 


CREATING 


Creating a Posted Sales Shipment requires a variety of operational steps that are beyond 
the scope of this book, as there may be a wide array of shipment requirements. In the most 
basic configurations, it involves Posting a Sales Order with the Ship choice. 


Bound Actions 


No bound actions. 


e customers (page 110) 

e countryRegion (page 402) 

e paymentTerms (page 445) 

e shipmentMethods (page 457) 
e salesShipmentLines (page 224) 
e dimensionSetLines (page 427) 


| Version Changes 


24.0 Field Renamed: billToCustomerld 
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Chapter 40: Sales Shipment Lines 


Unlike other Sales Document Line endpoints, the Sales Shipment Lines endpoint points 
exclusively to the Posted Sales Shipment Lines in Business Central, as there is not an unposted 
form. 


This also means it does not rely on any aggregate mechanisms. 


Primary Key 


Document No. The identifier of the Sales Shipment. The field is 20 characters and 
alphanumeric. 

Line No. The numeric identifier for the specific Sales Shipment Line. It is unique 
only in the given Sales Shipment. Integer Identifier. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesShipments (2a8d8353- 
df3a-ed11-bbae-6045bd8e554a)/salesShipmentLines/Sentity", 

"Qodata.etag": "W/N"JzE5OzMONjY5ODIzMjUzMTg4Mzc5OTcxOzAwOyc-N"", 

"id": "358d88353-df3a-edll1-bbae-6045bd8e554a", 

"documentId": "2a8d8353-df3a-ed11-bbae-6045bd8e554a", 


Vdocument Nols M SS EET 
"sequence": 10000, 

"lineType": "Item", 
"lineObjectNumber": "1928-S", 
"description": "AMSTERDAM Lamp", 
ikekersiereijone aoa Me MIM 
"unitOfMeasureCode": "PCS", 


puse coU Sa ey 
Weenie ^ B Sin 


"discountPercent": 0, 
WeaxPercent< 5, 
"ishemeniateu 4-999 29 


BUSINESS CENTRAL ENTITY: 
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K 


S-SHPT102198 - School of Fine Art 


Posted Sales Shipment 


Home Shipment Certificate of Supply 


General 


No. documentNo Requested Delivery Date 
Customer School of Fine Art Promised Delivery Date 
Contact B Quote No 


Posting Date j Order No 


Planned 
Delivery 
Date 


ROME Guest Chair, green ^ 9/23/2022 X 9/23/2022 
SYDNEY Swivel Chair, green 9/23/2022 /23/2022 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesShipments (2a8d8353-df3a-ed11-bbae- 
6045bd8e554a) /salesShipmentLines 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesShipments (2a8d8353-df3a-ed11-bbae- 
6045bd8e554a) /salesShipmentLines (358d8353-df3a-ed11-bbae-6045bd8e554a) 


Example GET Request URI Single (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})salesShipmentLines (358d48353-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (1 entity shown from a longer list): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesShipments (2a8d8353- 
df3a-ed11-bbae-6045bd8e554a)/salesShipmentLines", 

"value": [ 


{ 


"Qodata.etag": "W/N"JzE5OzMONjY5ODIzMjUzMTg4Mzc5OTcxOzAwOyc-N"", 
"id": "3584d48353-df3a-edll-bbae-6045bd8e554a", 
"documentId": "2a848353-df3a-edll-bbae-6045bd8e554a", 
Nelocument: NOt M SSEIPDIOPOONU 

"sequence": 10000, 
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"lineType": "Item", 


"lineObjectNumber": "1928-S", 
"description": "AMSTERDAM Lamp", 
"iglexeealqoe deuda ia. UU 
"unitOfMeasureCode": "PCS", 


npa Prdcols SU T 
"ienpeucuEdlie/ ^ BP Sin 
"discountPercent": 0, 
"taxPercent": 5, 


"shipmentDate": "2024-09-23" 
lg 
CRUD Steps 


CREATING 


Creating a Posted Sales Shipment requires a variety of operational steps that are beyond 
the scope of this book, as there may be a wide array of shipment requirements. In the most 
basic configurations, it involves Posting a Sales Order with the Ship choice. 


Bound Actions 


No bound actions. 


e salesShipments (page 219) 
e accounts (page 38) 
e dimensionSetLines (page 427) 


| Version Changes 


22.0 Fields Added: description2 


17.3 Added. 
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PART 4: PURCHASING 


In this Part, we will cover the various Purchasing related endpoints in Business Central. 


If you need to understand the document flow, status fields, or to customize the Purchase 
Document endpoints, it is strongly recommended to read Part 8: Chapter 88: Sales & Purchase 
Documents (page 506). 
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Chapter 41: Aged Accounts Payables 


The Aged Accounts Payables endpoint allows you to get the data that comprises the 
Aged Accounts Payable report. 


Primary Key 


N/A This API is a query that does not directly expose a table, so there is no 
Business Central primary key. Each record in the results will be unique 
per Vendor. 


Field Map 


API JSON: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}}) /agedAccountsPayables/Sentity 


" 
, 


"Qodata.etag": "W/N"JzIwOzEyNzIxMzM1ODYxODIzNzcOMzQwMTswMDsnN"", 
"vendorId": "7115971e-df3a-edll-bbae-6045bd8e554a", 
"vendorNumber": "10000", 

Iimame matrem TNE. 

"currencyCode'; wt" 

"balanceDue": 2071.13, 

"currentAmount": 0, 


"periodlAmount": O0, 
"period2Amount": 0, 
"period3Amount": 2071.13, 
"agedAsOfDate": "2024-06-03", 
"periodLengthFilter": "30D" 


BUSINESS CENTRAL ENTITY: 
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13/03/21 
Rent 


Before 
13/01/21 


salance 

10000 Fabrikas, Inc. a -1,267.50 0.00 -3,267.50 0.00 0.00 0.00 
20000 First Up Consultants ae -5,751.88 0.00 751.88 0.00 0.00 0.00 
30000 Graphic Design Institute as 74,273.50 0.00 74,273.50 0.00 0.00 0.00 
40000 wide world reporters cae :13,921.13 0.00 *13,921.13 0.00 0.00 0.00 
$0000 Nod Publishers car *13,217.88 0.00 -13,217.88 0.00 0.00 0.00 
Tota! 
acy) -36,431.89 0.00 -36,431.89 0.00 0.00 0.00 

on 100% o o o 
Currency Specification car -36,431.09 0.00 -36,431.09 0.00 0.00 0.00 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/agedAccountsPayables 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/agedAccountsPayables (7115971e-df3a-edl1-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /agedAccountsPayables", 
"value": [ 


{ 


"Qodata.etag": "W/N"JzE5OzY5MzOIMzU2OTIzMzg2MTEONjExOzAwOyc-N"", 
"vendorId": "00000000-0000-0000-0000-000000000000", 
"vendorNumber": "", 

manene UT etai 
"currencyCode": 
"balanceDue": 49421.55, 
"currentAmount": 0, 
"periodlAmount": 0, 
"period2Amount": 0, 
"period3Amount": 49421.55, 
"agedAsOfDate": "2024-06-03", 
"periodLengthFilter": "30D" 


"wn 
, 


"Qodata.etag": "W/N"JzIwOzEyNzIxMzM1O0DYxODIzNzcOMzQwMTswMDsnN"", 
"vendorId": "7115971e-df3a-edll-bbae-6045bd8e554a", 
"vendorNumber": "10000", 

names- mcyereablebuu. Ine. Wp 

Ucumsmemneweose in 

"balanceDue": 2071.13, 

"currentAmount": O0, 
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"periodlAmount": 0, 
"period2Amount": O0, 
"period3Amount": 2071.13, 
"agedAsOfDate": "2022-10-26", 
"periodLengthFilter": "30D" 


"Qodata.etag": "W/N"VSJzIwWOZzEOODk5NTcxNzYyMDExODU2NjgzMTswMDsnN"", 
"vendorId": "7215971e-df3a-edll-bbae-6045bd8e554a", 
"vendorNumber": "20000", 
“name. taste Up Consultants, 
Ucunscenewode M 
"balanceDue": 4903.88, 
"CcurrentAmount": 0, 
"periodlAmount": 0, 
"period2Amount": 0, 
"period3Amount": 4903.88, 
"agedAsOfDate": "2024-06-03", 
"periodLengthFilter": "30D" 
), 


ea) 
CRUD Steps 


CREATING 


Creating and posting an Invoice for a vendor will add data to this report resultset. 
Instructions on creating and pointing invoices is beyond the scope of this book. 


Bound Actions 


No bound actions. 


Navigations 


e vendors (page 291) 


No notable changes. 
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Chapter 42: Apply Vendor Entries 


When payments are received into Business Central from a Vendor, a Payment Journal Line 
gets created. While you can specify a specific invoice to apply the payment to, this is a 1 to 1 
payment matching using the Applies-To Document No. field. 


Sometimes a vendor makes a single payment to cover several invoices. You cannot specify 
multiple invoice numbers in a single column. Inside Business Central, this is done via the Apply 
Entries... action from the Payment Journal: 


Apply Vendor Entries - 20000 - First Up Consultants 


General 


Posting Date 4/11/2022 
Jocument Type Payment Amount 1,000.00 
Document Ne G04002 Remaining Amount 1,000.00 


Vendor Name 


Home Entry 


Typ N N Y 
Invoice 107196 20000 First Up Invoice 107196 -2,214.13 -2,214.13 0.00  3/31/202. 
Invoice 107199 20000 First Up Invoice 107199 -1,255.89 -1,255.89 0.00  3/31/202. 


Invoice 107203 20000 First Up Invoice 107203 -1,433.86 -1,433.86 000 3/31/202, 


Appln. Currency Amount to Apply Pmt. Disc. Amount Rounding Applied Amount Available Amount Balance 


0.00 ).00 1,000.00 1,000.00 


In this screen, a Business Central user marks the Invoices this payment should apply to 
and how much. Via the endpoint, you can only choose which Payments to apply to, not the 
amount. 


Because this is tied to the specific Payment Journal Line (the Vendor Payment endpoint), 
this is the rare case of a many levels deep navigation. To get lists of possible Invoices to apply, 
you will need the Vendor Payment Id. To get the Vendor Payment Id, you'll need the records 
from the Vendor Payment Journals. 


Note: In versions below BC 18, a critical bug in using this endpoint that makes its use very 
difficult. Please see Part 8: Chapter 91: API Bugs (page 517). 
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Primary Key 


The id field here is tied to the Vendor Ledger Entry's systemld field, but the Primary Key 
of that table, the Entry No. field (an integer), is not available via this endpoint. 


Field Map 


The fields align with the Apply Vendor Entries page displayed fields, which are from the 
Vendor Ledger Entries. 


API JSON: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /vendorPaymentJournals (335a25 
23-df3a-ed11-bbae-6045bd8e554a) /vendorPayments (bd67£8 4b-2c9f-ed11-9a8a- 
6045bd02a733) /applyVendorEntries/Sentity", 

"Qodata.etag": "W/N"JzE5Ozg2NjUzMjM5MjYyMDc5NDczMTcxOzAwOyc-N"", 

"id": "41a6a271-df3a-edl1-bbae-6045bd8e554a", 

"applied": false, 


Marepisste soc M 

WsOsedme Denice s 29212 .(0]5) 1094 7 

"documentType": "Invoice", 

"documentNumber": "108196", 
"externalDocumentNumber": "107196", 
"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 

Ice seus tete m TT codec c STO RTT 
"remainingAmount": -2214.13, 
"lastModifiedDateTime": "2024-06-03T14:09:58.2362" 


BUSINESS CENTRAL ENTITY: 


Apply Vendor Entries - 20000 - First Up Consultants 


General 


Posting Date 
Document Type 
Document No. 


Vendor Name 


Applies-to Document Document Vendor No.t ^ Vendor Remaining Remaining 
ID Posting Date Type No. b d Name Description Amount Amount 


3/10/2022 Invoice 107196 20000 First Up... Invoice 107196 -2,214.13 -2,214.13 
3/12/2022 Invoice 107199 20000 First Up... Invoice 107199 -1,255.89 -1,255.89 
3/15/2022 Invoice 107203 20000 First Up... Invoice 107203 -1,433.86 -1,433.86 
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The only field that is not directly mapped is the applied field, which is simply a Boolean 
to note if the appliesToId is populated. 


GET 


For a given Id from a Vendor Payment, you can get a list of valid Entries to apply to as a 
Navigation: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/vendorPayments (bd67£84b-2c9f-ed11-9a8a- 
6045bd02a733) /applyVendorEntries 


This will result in an array of available Invoices to apply a payment to for this Vendor: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadatafcompanies ({ {companyID}}) /vendorPayments (bd67£84b- 
2c9f-ed11-9a8a-6045bd02a733) /applyVendorEntries", 
"value": [ 


{ 


"@odata.etag": "W/\"JzE30zY4NzQyNZEwMDIwMDE5MDUwMTswMDsn\"", 
"id": "41a6a271-df3a-edll-bbae-6045bd8e554a", 

"applied": true, 

“app bies Toron “G04002, 

VpoOcsiting batter 21022 — 01S aL (MET 


"documentType": "Invoice", 

"documentNumber": "108196", 
"externalDocumentNumber": "107196", 
"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 
NidesermilperTont p. answaeuteis di mat eM 
"remainingAmount": -2214.13, 
"lastModifiedDateTime": "2024-06-03T14:09:58.2362" 


"Qodata.etag": "W/\"JzIwOzE20TcyMDk4MDgzNjc4Njg3NjgzMTswMDsn\"", 
"id": "96a6a271-df3a-edll-bbae-6045bd8e554a", 
"applied": false, 


irarpsiesT oic 
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"documentType": "Invoice", 

"documentNumber": "108199", 
"externalDocumentNumber": "107199", 
"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 
WkeexesedgsiEsLei "m Vuüpswaoster digo). 

Vremalni ngAmoume BO 
"lastModifiedDateTime": "2024-06-03T14:09:58.2362" 


"@odata.etag": "W/N"JzIwOzEOMjgzMzYyNzkwOTIyNjg5NDIyMTswMDsnN"", 
"id": "14a7a271-df3a-edl1-bbae-6045bd8e554a", 
"applied": false, 


Wapp les homes wis, 

ISOM Dees a Asl 
"documentType": "Invoice", 
"documentNumber": "108203", 
"externalDocumentNumber": "107203", 
"vendorNumber": "20000", 
"vendorName": "First Up Consultants", 
Me TobanoiohRoje URN Bo oho M NO DAC u 
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"remainingAmount": -1433.86, 
"lastModifiedDateTime": "2024-06-03T14:09:58.2362" 


You can also GET a single result by supplying the application entry's id: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /vendorPayments (bd67£84b-2c9f-ed11-9a8a- 
6045bd02a733) /applyVendorEntries (41a6a271-df3a-ed11-bbae-6045bd8e554a) 


PATCH 


The only field you can update via a PATCH call is the applied field, setting it to true or 
false. 


Example Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/vendorPayments (bd67£84b-2c9f-ed11-9a8a- 
6045bd02a733) /applyVendorEntries (41a6a271-df3a-ed11-bbae-6045bd8e554a) 


Example Request Body: 


"applied": true 


Example Request Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /vendorPayments (bd67f£84b- 
2c9f-ed11-9a8a-6045bd02a733)/applyVendorEntries/S$entity", 

"Qodata.etag": "W/N"JzE3OzYA4NzOyNzEWMDIwMDESMDUwMTswMDsnN"", 

"id": "41a6a271-df3a-edll1-bbae-6045bd8e554a", 

"applied": true, 

"appliesToId": "G04002", 

JMerexsEmueKeDEE US WAO ZZ (15) 194 7 


"documentType": "Invoice", 

"documentNumber": "108196", 
"externalDocumentNumber": "107196", 
"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 

inde semp esiremiv Semi disce STO 9G 

remate Amount aep 2d A 
"lastModifiedDateTime": "2024-06-03T14:09:58.2362" 


However, the moment you flag applied to true, the Payment Journal line is no longer 
available via the API. 


Please see Part 8: Chapter 91: API Bugs (page 517). 
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CRUD Steps 


How to create a Payment Journal Line is documented in the Vendor Payment chapter 
(page 298). However, creating Invoices to apply a payment to is beyond the scope of this book. 
Any open Invoice for a Vendor to be paid should appear here. 


Bound Actions 


No bound actions. 


e vendors (page 291) 


| Version Changes 


23.0 Added lastModifiedDateTime. 


18.0 Added 
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Chapter 43: Purchase Credit Memo 


The Purchase Credit Memo endpoint allows access to Purchase Credit Memo and 
documents. When working with this endpoint, it is strongly recommended to read Part 8: 
Chapter 88: Sales & Purchase Documents (page 506). 


The Sales Credit Memos endpoint allows access to both Sales Credit Memos and Posted 
Sales Credit Memos documents. When working with this endpoint, it is strongly 
recommended to read Part 8: Chapter 88: Sales & Purchase Documents (page 506). 


Primary Key 


No. The identifier of the Purchase Credit Memo or Posted Purchase Credit 
Memo. The field is 20 characters and alphanumeric. 

Posted The indication of whether the Purchase Credit Memo is posted or not. 
The field is a Boolean (Yes or No) indicator. 


Field Map 


Note: With this endpoint, a large amount of data is available, so it 
is key to consider using smart $£ilter and $select options. See 


Part 8: Chapter 89: Performance (page 511) and Part 1: Chapter 
2: Reading / GET (page 17) for more information. 


API JSON: 


"@odata.etag": "W/\"JzIwOzE1MjU3NTOxOTkzNzEyNTESMDgwMTswMDsn\"", 
"id": "970971c8-4418-ef11-9467-d62465a5064f", 

ormb eds MEIN Od 

"creditMemoDate": "2024-01-01", 

JheroxenesuswelbewE ug UAM 2 2 

"dueDate": "2024-01-01", 

"vendorId": "c37ef4e9-9dfc-eel11-9f8c-6045bde98c0Of", 
"vendorNumber": "30000", 

"vendorName": "Graphic Design Institute", 
"payToVendorId": "c37ef4e9-9dfc-eel1-9f8c-6045bde98cOf", 
"payToVendorNumber": "30000", 

"payToName": "Graphic Design Institute", 
"buyFromAddressLinel": "33 Hitech Drive", 
"buyFromAddressLine2": "", 

Wouivionleaew EMTA, 
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YOUVE NOmMCOuUnEry a MURS" 5 

Ub uyEdSOmsisa tcm ENT 

UiouyEmombositodec: a2" 

"payToAddressLinel": "33 Hitech Drive", 
"payToAddressLine2": "", 

Mpa Lo Gesn TM TTE 

ioo oum va EU SU 

"payToState" : SORT RUP 

lodo oOsSi ocu NUI tU 

"shortcutDimensionlCode": "", 

"shortcutDimension2Code": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"currencyCode": "USD", 

"paymentTermsId": "c47cf4e9-9dfc-eell1-9f8c-6045bde98cO0f", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
Wiexbüstelorsue ree S MIS. 

"pricesIncludeTax": false, 

Meise eue ATRIDES NI 

"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 

urota ltax mounta: Ol 

"totalAmountIncludingTax": 0, 

USt MUT as aft 

"lastModifiedDateTime": "2024-05-22T14:08:38.2372", 
"invoiceld": "00000000-0000-0000-0000-000000000000", 
"invoiceNumber": "", 

"vendorReturnReasonId": "00000000-0000-0000-0000-000000000000" 


BUSINESS CENTRAL ENTITY: 


Work Date: 22/01/20 


109001 - CoolWood Technologies 


Home  Print/Send Credit Memo Incoming Document 


fà Find entries. 
General 


109001 Contact Mr. Richard Bready 
CoolWood Technologies osting Date 08/01/2026 
Buy-from V 08/01/2026 
35 Hitech Drive Docu e 08/01/2026 
109001 


Portsmouth Vendor Cr. Memo No. KR95-02-01 


PO7 2HI 
GB 


CT000133 


mr.richard.breadyG contoso.com 


Lines Manage Line 
E 3x E Deferral Schedule 


Return Reason Unit of Direct Unit Cost Line Amount 
Code Quantity Measure Code Excl. VAT Unit Price (LCY) Line Discount % Excl. VAT Deferral Code 


40 PCS 708.60 974.80 28,344.00 


Invoice Discount Amount Excl. VAT 0.00 Total VAT (GBP) 7,086.00 


Total Excl. VAT (GBP) 28,344.00 Total Incl. VAT (GBP) 35,430.00 
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Credit Memo Details 


Currency Code EE Applies-to Doc. Type 


Department Code Applies-to Doc. No. 
Project Code Correction 


Location Code 


Shipping and Payment 


Ship-to Pay-to 
Name CoolWood Technologies Name CoolWood Technologies 
Address 33 Hitech Drive. Address 33 Hitech Drive 
Address 2 Address 2 
City Portsmouth City 
Ship-to County Pay-to County 
Post Code PO72HI Post Code PO7 2HI 
Country/Region GB Country/Region GB 
Contact Mr. Richard Bready Contact No. CT000133 
Applicable For Service Declaration C] Phone No. 
Mobile Phone No. 
Email mr.richard.breadyG contoso.com 


Contact Mr. Richard Bready 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/purchaseCreditMemos 


Example GET Response (2 entries): 


{ 
"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/$metadatafcompanies ({{companyID}}) /purchaseCreditMemos", 
value sai 
{ 
"@odata.etag": "W/N"JzIWOzE1MjU3NTOxOTkzNzEyNTES5MDgwMTswMDsnN"", 
Vids “O709Tles=4418-enll— 9467 -d6Zz4o5a5064i, 
Umum ete LOOM, 
"creditMemoDate": "2024-01-01", 
VASO EINE Dene! p U2) Pre mM 
Newebatel 2024 0f Ow 
"vendorId": "c37ef4e9-9dfc-eell-9Ff8c-6045bde98c0F", 
"vendorNumber": "30000", 
"vendorName": "Graphic Design Institute", 
"payToVendorId": "c37ef4e9-9dfc-eell-9f£8c-6045bde98cOf", 
"payToVendorNumber": "30000", 
"payToName": "Graphic Design Institute", 
"buyFromAddressLinel": "33 Hitech Drive", 
"buyFromAddressLine2": "", 
IUE Cm bte vo AMM, 
Wiley ibszIthsetor nexoxiDouEsc y 8 MOIS. 
vouyvbnomo tate s AEE 
ViNlVECOomeosicode = NN 
"payToAddressLinel": "33 Hitech Drive", 
"payToAddressLine2": "", 
“payro reya MEAN 
Moawikocouimiciey’ MAIS 
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"payToState" gq Wi, 


Jewels teodet s Vb 

"shortcutDimensionlCode": "", 

"shortcutDimension2Code": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"cusrneneytcodet USDE, 

"paymentTermsId": "c47cf4e9-9dfc-eell1-9f8c-6045bde98cO0f", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
purchasers. u7 


"pricesIncludeTax": false, 
"discountAmount": 0, 
"discountAppliedBeforeTax": false, 
tota l AmountcExe l eias 
"totalTaxAmount": 0, 
"totalAmountIncludingTax": 0, 


MSE ESA Dra EE 

"lastModifiedDateTime": "2024-05-22T714:08:38.2372", 
"invoiceld": "00000000-0000-0000-0000-000000000000", 
"invoiceNumber": "", 


"vendorReturnReasonId": "00000000-0000-0000-0000-000000000000" 


"Qodata.etag": "W/N"JzESOzg3MTkyOTI1MDUONDU2NjQ3NjQxOzAwOyc-N"", 
"id": "10309dd4-4418-ef11-9467-d62465a5064f", 

Arum er: eO 

"creditMemoDate": "2021-01-01", 

posteingpatet W202 Oss 2 2M 

"dueDate": "2021-01-01", 

"vendorId": "c27ef4e9-9dfc-eell-9f8c-6045bde98c0f", 
"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 

"payToVendorId": "c27ef4e9-9dfc-eell-9f8c-6045bde98cOf", 
"payToVendorNumber": "20000", 

"payToName": "First Up Consultants", 
"buyFromAddressLinel": "100 Day Drive", 
"buyFromAddressLine2": "", 

MestySieonestiEs/ B elm 

Uy mEromecountn y US, 

wy Omsicat em I 

UouyEromPostcodeV": 62 3/91 

"payToAddressLinel": "100 Day Drive", 
"payToAddressLine2": "", 

Spay loCrtva 3s Mela eo 

iota umts 3s VOSS, 

"payToState": Tena 

"payToPostCode": "61236", 

"shortcutDimensionlCode": "", 

"shortcutDimension2Code": "", 

"currencyId": "c77cf4e9-9dfc-eel1-9f8c-6045bde98cO0Of", 
"currencyCode": “EUR, 

"paymentTermsId": "c47cf4e9-9dfc-eel1-9f8c-6045bde98cO0f", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
Wiexbüstelorsverexe Mg MIN 

"pricesIncludeTax": false, 

Wchiscouneamebinics: (0 

"discountAppliedBeforeTax": true, 

Miles asibAmemie Bio eiaa INTRO TN, 

vota lTaxAmount 4: SHE 3 

"totalAmountIncludingTax": 1261.94, 


Wiciceniebis Ye E DE 

"lastModifiedDateTime": "2024-05-22T14:42:59.6072", 
"invoiceld": "00000000-0000-0000-0000-000000000000", 
"invoiceNumber": "", 


"vendorReturnReasonId": "00000000-0000-0000-0000-000000000000" 
), 
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Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCreditMemos (970971c8-4418-ef11-9467-d62465a5064£) 


Example GET Response (Single): 


{ 

"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseCreditMemos/$en 
NENA 

"@odata.etag": "W/N"JzIwOzE1MjU3NTOxOTkzNzEyNTES5MDgwMTswMDsnN"", 

"id": "970971c8-4418-ef11-9467-d62465a5064f", 


mumos raO 
"creditMemoDate": "2024-01-01", 
"postingpartetki ANIME 0m Mn 


"dueDate": "2024-01-01", 

"vendorId": "c37ef4e9-9dfc-eel11-9f8c-6045bde98c0Of", 
"vendorNumber": "30000", 

"vendorName": "Graphic Design Institute", 
"payToVendorId": "c37ef4e9-9dfc-eel1-9f8c-6045bde98cOf", 
"payToVendorNumber": "30000", 

"payToName": "Graphic Design Institute", 
"buyFromAddressLinel": "33 Hitech Drive", 
"buyFromAddressLine2": "", 

A'iowii Eam Gs test AM Re ELT 

buy a romCounery =: SUS, 

MPUy EOMsizadieeww CELY, 

UouyEbombosiode CONI 

"payToAddressLinel": "33 Hitech Drive", 
"payToAddressLine2": "", 

ode Ges EM 

ino evalyo oum US 

"payToState": TETU 

TpayloPostCodenk WISIS 

"shortcutDimensionlCode": "", 

"shortcutDimension2Code": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
WeurrencyCode™: "USD" 

"paymentTermsId": "c47cf4e9-9dfc-ee11-9f8c-6045bde98c0f", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
“purchaser es MINUS. 

"pricesIncludeTax": false, 

"discountAmount": O0, 

"discountAppliedBeforeTax": false, 
NEotalAmountkxeludiungiasc': 07 

Grota TaxAmounts: IP 
"totalAmountIncludingTax": 0, 

Meneehe bis Miphechcie n 

"lastModifiedDateTime": "2024-05-22T14:08:38.2372", 
"invoiceld": "00000000-0000-0000-0000-000000000000", 
"invoiceNumber": "", 

"vendorReturnReasonId": "00000000-0000-0000-0000-000000000000" 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/purchaseCreditMemos 


Example POST Request Body: 


"creditMemoDate": "2024-05-29", 
"vendorNumber": "20000", 
"currencyCode": "EUR" 


Example POST Response: 


{ 

"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({{companyID}}) /purchaseCreditMemos/Sen 
CHENA 

"@odata.etag": "W/\"JzE50zYONDkxNzUZMTkwMTE1MjU4NjAxOzAwOyc=\"", 

Vigil WelaZo0le-b42 let ill 9467 d624065495)0/64f7 

"number": "1004", 

"creditMemoDate": "2024-05-29", 

I oos gi ausete A WA 65-09" 

"dueDate": "2024-05-29", 

"vendorId": "c27ef4e9-9dfc-ee11-9f8c-6045bde98cOf", 

"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 

"payToVendorId": "c27ef4e9-9dfc-eel1-9f8c-6045bde98cOf", 

"payToVendorNumber": "20000", 

"payToName": "First Up Consultants", 

"buyFromAddressLinel": "100 Day Drive", 

"buyFromAddressLine2": "", 

Uo Eromestteyils Met Cbeao 

Ioui Ease moms NO SR 

"buyEromsiateV: Im 

"bouwyBBombPositcodeUt: t G2 36107 

"payToAddressLinel": "100 Day Drive", 

"payToAddressLine2": "", 

JisyesvaMO(CubEN 3 Ulmer 

eal e um bove MUS 

JAsrstwlbrefSiselbes p, MII, 

Wsseylowosrcoces Vo SU 

"shortcutDimensionlCode": "", 

"shortcutDimension2Code": "", 

"currencyId": "c77cf4e9-9dfc-eel11-9f8c-6045bde98cOf", 

"currencyCode": "EUR", 

"paymentTermsId": "c47cf4e9-9dfc-eell-9f8c-6045bde98cO0f", 

"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 

Inouncehaseni mu 

"pricesIncludeTax": false, 

"discountAmount": O0, 

"discountAppliedBeforeTax": false, 

"totalAmountExcludingTax": 0, 

"totalTaxAmount": 0, 

"totalAmountIncludingTax": 0, 

Ursneehebiss DENE E 

"lastModifiedDateTime": "2024-06-03T14:18:03.4332", 

"invoiceId": "00000000-0000-0000-0000-000000000000", 


PART 4: PURCHASING 
CHAPTER 43: PURCHASE CREDIT MEMO 


"invoiceNumber": "", 
"vendorReturnReasonId": "00000000-0000-0000-0000-000000000000" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCreditMemos (de9f5d62-b421-ef11-9467-d62465a5064f£) 


Example PATCH Request Body: 


VoOstlng Matsa mene O24) —AiGuie 
"vendorNumber": "20000", 
NeurrencyCode USD 


Example PATCH Response: 


{ 

"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({{companyID}}) /purchaseCreditMemos/S$en 
(galig o 

"Qodata.etag": "W/N"JzIWOzE2OTAA4NzYzNDA1NjOwNTCS5MDAyMTswMDsnN"", 

"id": "de9f5d62-b421-ef11-9467-d62465a5064f", 

V rumen: O5 

"creditMemoDate": "2024-06-03", 

iso dine Dice S W202 OS 2 (e 

"dueDate": "2024-06-03", 

"vendorId": "c27ef4e9-9dfc-eell-9f8c-6045bde98c0F", 

"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 

"payToVendorId": "c27ef4e9-9dfc-eell1-9f8c-6045bde98cO0f", 

"payToVendorNumber": "20000", 

"payToName": "First Up Consultants", 

"buyFromAddressLinel": "100 Day Drive", 

"buyFromAddressLine2": "", 

MepyimaoiGsiey Mg Mme 

WloishyAtsatariCrobbone aye: MOIS 

VHuyEromotate sali 

'UbouyEnBombosteocde eto Sone, 

"payToAddressLinel": "100 Day Drive", 

"payToAddressLine2": "", 

Vere NAE OO atiev e. Melaisiierexe on 

Spay oCount r y NU SI. 

"payToState" : ATIG 

"payToPostCode": "61236", 

"shortcutDimensionlCode": "", 

"shortcutDimension2Code": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 

Ucunsrenceve ode E USIMM 

"paymentTermsId": "c47cf4e9-9dfc-eell-9f8c-6045bde98cO0f", 

"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 

iuc nm 

"pricesIncludeTax": false, 

"discountAmount": O0, 

"discountAppliedBeforeTax": false, ) 


PART 4: PURCHASING 
CHAPTER 43: PURCHASE CREDIT MEMO 


"totalAmountExcludingTax": 0, 
"totalTaxAmount": 0, 
"totalAmountIncludingTax": 0, 


voratus et Miphetcurie 

"lastModifiedDateTime": "2024-06-03T14:20:10.9972", 
"invoiceld": "00000000-0000-0000-0000-000000000000", 
"invoiceNumber": "", 


"vendorReturnReasonId": "00000000-0000-0000-0000-000000000000" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCreditMemos (de9£5d62-b421-ef11-9467-d62465a5064f) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


Note that since this can allow deletion of Posted Sales Credit Memos, deletion may fail 
depending on system setting constraints on posted documents. 


CRUD Steps 


CREATING 


From the Purchase Credit Memo list, click on the New button in the Action Bar. 


Purchase Credit Memos: All V Ø Search (6 ) Analyze -FNew Ú Delete [2 Release v lif Post w Credit Memo v More options 


Vendor 
Buy-from Authorizati.. ^ Vendor Cr. Assigned User 
Vendor No. Buy-from Vendor Name No. Memo No. Location Code ID Due Date Amount 


30000 Graphic Design Institute 1/1/2024 0.00 


20000 First Up Consultants 1/1/2021 0.00 


This will open a blank Purchase Credit Memo card. Select a Vendor, which should 
automatically assign a Purchase Credit Memo No. 


General 


Show more 


Vendor Name Graphic Design Institute D Vendor Authorization No. 


Contact Bryce Jasso sn Vendor Cr. Memo No. 


Due Date 4/8/2024 Status 


Expected Receipt Date 


creates it enough to be available for the API. 


PART 4: PURCHASING 
CHAPTER 43: PURCHASE CREDIT MEMO 


UPDATING 


Change a field in the General section, such as the Due Date. 


DELETING 


For unposted documents, use the delete button in the Action bar. Posted documents can 
not be deleted. 


Bound Actions 


e Post 
e Cancel 


e vendors (page 291) 

e countryRegion (page 402) 

e currencies (page 407) 

e paymentTerms (page 445) 

e shipmentMethods (page 457) 

e purchaseOrderLines (page 276) 
e attachments (page 378) 

e dimensionSetLines (page 427) 


History 


| Version Changes 


22.0 Added. 
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Chapter 44: Purchase Credit Memo Lines 


The Purchase Credit Memo Lines endpoint allows access to Purchase Credit Memo 
Lines. When working with this endpoint, it is strongly recommended to read Part 8: Chapter 
88: Sales & Purchase Documents (page 506). 


Primary Key 


Document Id The generated identifier for the Purchase Order Line is created and used 
under the hood by Business Central to perfectly separate and identify. 
The field is a GUID. It is locked and managed by BC. 
Line No. The numeric identifier for the specific Purchase Order Line. It is unique 
only in the given Purchase Order. Integer Identifier. 

Note that this is an aggregate table, so it often comes from a Document Line table with 
a primary key of Document No. and Line No., but the aggregate table uses the Document Id 
to ensure uniqueness. 


Field Map 


API JsoN: 


"Qodata.etag": "W/\"JzE50zc1MTQ2Njk5MDI 4MTIwMTQ3MDkxOzAwOyc=\"", 
"id": "87d65c66-b521-ef11-9467-d62465a5064f", 

"documentId": "de9f5d62-b421-ef11-9467-d62465a5064f", 
"sequence": 10000, 

"itemId": "c77ef4e9-9dfc-ee11-9f8c-6045bde98cOf", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 

clesie on NU PARINSGUSSI Charr, rac tur 
"unitOfMeasureId": "1939ccee-9dfc-eel11-9f8c-6045bde98cO0f", 
"unitOfMeasureCode": "PCS", 

Ton ECOS te: PSI Sr 


Wreiieioncaeyy V8 2r 

"discountAmount": O0, 
"discountPercent": 0, 
"discountAppliedBeforeTax": false, 
amount Exe ludingtaxs B. TOi 
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Intra oce = UR URINTMELU IR U, 

"taxPercent": 6.00133, 

"totalTaxAmount": 0, 

Wamountine lucumclax! 0), 

"invoiceDiscountAllocation": 0, 

"netAmount": 300.6, 

"netTaxAmount": 18.04, 

"netAmountIncludingTax": 318.64, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


"@odata.etag": "W/N"JzIwOzExNzI4NjY1MjE4MzAyMDC1NjY3MTswMDsnV"", 
"id": "b9313a6e-b521-ef11-9467-d62465a5064f", 
"documentId": "de9f5d62-b421-ef11-9467-d62465a5064f", 
"sequence": 20000, 

"itemId": "c87ef4e9-9dfc-ee11-9f8c-6045bde98c0f", 
"accountId": "00000000-0000-0000-0000-000000000000", 
"lineType": "Item", 

"lineObjectNumber": "1906-S", 

"description": "ATHENS Mobile Pedestal", 
"unitOfMeasureId": "1939ccee-9dfc-ee11-9f8c-6045bde98c0f", 
"unitOfMeasureCode": "PCS", 

unus osi: ESSO 

JienneWenedLiEN7^ B (Ur 

"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 

"amountExcludingTax": 0, 

raeo den SEINE TEINIREUEBSU 

"taxPercent": 0, 

"totalTaxAmount": 0, 

Wamount ine lucunghax! |=) 0), 

"invoiceDiscountAllocation": 0, 

"netAmount": 0, 

"netTaxAmount": O0, 

"netAmountIncludingTax": 0, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


BUSINESS CENTRAL ENTITY: 


item Reference Direct Unit Cost Tax Group 
No. Description Quantity ^ Measi ode Excl. Tax Tax Area Code Code 


PARIS Guest Chair, black 150.30 ATLANTA, GA FURNITURE 300.60 


ATHENS Mobile Pedestal 338.20 ATLANTA, GA FURNITURE 1,352.80 


Amount Line Discount Department Customergro... 
Including Tax Amount ty. to Assign y. ASSI Code Code 


318.64 
1,433.96 
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A variety of fields are either unavailable on the Page by default or are unavailable to 


personalize onto the page. Some fields are available only by their Id value and not code, such 
as the locationId / Location Code. 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCreditMemo (de9f5d62-b421-ef11-9467- 
d62465a5064£) /purchaseOrderLines 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCreditMemos (de9f5d62-b421-ef11-9467- 
d62465a5064f) purchaseCreditMemoLines (59d0ae10-4718-ef11-9467-d62465a5064£f) 


Example GET Request URI Single (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCeditMemoLines (87d65c66-b521-ef11-9467-d62465a5064f) 


Example GET Response (2 entities shown from a longer list): 


{ 

"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({{companyID}}) /purchaseCreditMemos (de9 
£5d62-b421-ef11-9467-d62465a5064f) /purchaseCreditMemoLines", 

"value": [ 


{ 


"Qodata.etag": "W/\"JzE50zc1MTQ2Nj k5MDI4MTIWMTO3MDkxOzAwOyc=\"", 
"id": "87d65c66-b521-ef11-9467-d62465a5064f", 

"documentId": "de9f5d62-b421-ef11-9467-d62465a5064f", 
"sequence": 10000, 

"itemId": "c77ef4e9-9dfc-ee11-9f8c-6045bde98c0f", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 

Wdescripelon" mU PABISSGUSIEMC Lad laci 
"unitOfMeasureId": "1939ccee-9dfc-eel11-9f8c-6045bde98cO0f", 
"unitOfMeasureCode": "PCS", 


“umi eCosta ISO) 5 Sin 

eiretier a iy 

"discountAmount": 0, 
"discountPercent": 0, 
"discountAppliedBeforeTax": false, 
"amountExcludingTax": 0, 

Ina ode = hURNTELURI IU, 
"taxPercent™: 6.00133, 

“cota lMmaxAmount 2 07 

Wamount ineludingrax 0), 
"invoiceDiscountAllocation": 0, 
"netAmount": 300.6, 
"netTaxAmount": 18.04, 
"netAmountIncludingTax": 318.64, 
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"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


"Qodata.etag": "W/N"JzIWOzExNzI4NjY1MjEA4MzAyMDCINjY3MTswMDsnN"", 
"id": "b9313a6e-b521-ef11-9467-d62465a5064f", 
"documentId": "de9f5d62-b421-ef11-9467-d62465a5064f", 
"sequence": 20000, 

"itemId": "c87ef4e9-9dfc-ee11-9f8c-6045bde98c0f", 
"accountId": "00000000-0000-0000-0000-000000000000", 
"lineType": "Item", 

"lineObjectNumber": "1906-S", 

"description": "ATHENS Mobile Pedestal", 
"unitOfMeasureId": "1939ccee-9dfc-ee11-9f8c-6045bde98cO0f", 
"unitOfMeasureCode": "PCS", 

I unusee oS SO 

JMienieuanesbiEs7 S (0), 

Vchisicouenemebinic Ss: (0) 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 

Wamounzrxelucdamoahasce 6 0), 

isa oce  WUIRINLIEUU SU 

"taxPercent": 0, 

"totalTaxAmount": 0, 

Wamount mnelucinglax |: 0r 

"invoiceDiscountAllocation": 0, 

"netAmount": 0, 

"netTaxAmount": 0, 

"netAmountIncludingTax": 0, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCreditMemos (de9f5d62-b421-ef11-9467- 
d62465a5064£) /purchaseCreditMemoLines 


Example POST Request Body: 


"lineType": "Item", 
"lineObjectNumber": "2000-S", 
“oguan tileys e. nl 


Example POST Response: 


{ 

"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseCreditMemos (de9 
£5d62-b421-ef11-9467-d62465a5064f) /purchaseCreditMemoLines/Sentity", 
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"Qodata.etag": "W/\"JzIwOzEwMTkwODEWNDE2NTkxODc2NDgzMTswMDsn\"", 
"id": "b32e4fdf-b621-ef11-9467-d62465a5064f", 

"documentId": "de9f5d62-b421-ef11-9467-d62465a5064f", 
"sequence": 30000, 

"itemId": "d97ef4e9-9dfc-ee11-9f8c-6045bde98c0f", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chair, green", 
"unitOfMeasureId": "1939ccee-9dfc-ee11-9f8c-6045bde98cO0f", 
"unitOfMeasureCode": "PCS", 

"pumskeletore ^ B Jas il 


Ueibieheicakiey M B Ato 

"discountAmount": O0, 

"discountPercent": O0, 

"discountAppliedBeforeTax": false, 
WaMoumErcelweamala sas O), 

WiceriCockas WiUISINIEMUIeIa 

MiaxPercenia): 599992» 

"totalTaxAmount": 0, 

Zamouneine ludimngtaxss m0; 
"invoiceDiscountAllocation": 0, 

"netAmount": 592.4, 

"netTaxAmount": 35.54, 

"netAmountIncludingTax": 627.94, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCreditMemos (10309dd4-4418-ef11-9467- 
d62465a5064£) /purchaseCreditMemoLines (b32e4fdf-b621-ef11-9467-d62465a5064£f) 


Example PATCH Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCreditMemoLines (b32e4fdf-b621-ef11-9467-d62465a5064f) 


Example PATCH Body: 


"lineType": "Item", 
We (bieigicabiey 4S 1s) 


Example PATCH Response: 


{ 

"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies (a9baaac8-9dfc-eel1-9f8c- 
6045bde98c0f) /purchaseCreditMemoLines/Sentity", 

"Qodata.etag": "W/\"JzIwOzEwNzY5NDM50DcyMzM5MTEI1NjJUSMTswMDsn\"", 

"id": "b32e4fdf-b621-ef11-9467-d62465a5064f", 

"documentId": "de9f5d62-b421-ef11-9467-d62465a5064f", 

"sequence": 30000, 
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"itemId": "d97ef4e9-9dfc-ee11-9f8c-6045bde98c0f", 
"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chair, green", 
"unitOfMeasureId": "1939ccee-9dfc-ee11-9f8c-6045bde98c0f", 
"unitOfMeasureCode": "PCS", 

Uibimahieerosie e ALA ill 


Sename Deya B. 13e 

"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
WaMouniErsxcelkucamahascn B. 0l 

Sirane oce VEU ENIUUEBSS 

NiaxPexcemta: on 999327 

"totalTaxAmount"':- 0, 

amount ine ludingolax e. (pr 
"invoiceDiscountAllocation": 0, 

"netAmount": 296.2, 

MnetlaxAmoune as TE, 

"netAmountIncludingTax": 313.97, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/purchaseCreditMemos (68d65a44-3d55-ed11-8c36- 
000d3a8dc661) /purchaseCreditMemoLines (0a6b8958-4818-ef11-9467-d62465a5064£) 


Example DELETE Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseCreditMemoLines (0a6b89b8-4818-ef11-9467-d62465a5064F£) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


Purchase Credit Memo Line can be created manually, though the particulars of creating 
Purchase Credit Memos are beyond the scope of this book. If the line has some information 
populated, it should be available via the API. 


UPDATING 
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Adjusting any field on an unposted Purchase Credit Memo Line, such as the Description, 
will update the line. 


DELETING 


Any unposted Purchase Credit Memo Line may be deleted, though some business 
restrictions may prevent removal. If it has been posted partially (shipped, invoiced, etc.), it 
might not be possible to delete the Purchase Credit Memo Line in progress. 


Bound Actions 


No bound actions. 


e purchaseCreditMemos (page 267) 
e items (page 323) 

e accounts (page 38) 

e unitsOfMeasure (page 471) 

e itemVariants (page 339) 

e dimensionSetLines (page 427) 


| Version Changes 
22.0 Added. 
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Chapter 45: Purchase Invoices 


The Purchase Invoices endpoint allows access to both Purchase Invoices and Posted 
Purchase Invoices documents. When working with this endpoint, it is strongly recommended 
to read Part 8: Chapter 88: Sales & Purchase Documents (page 506). 


Primary Key 


No. The number of the Purchase Invoice. The field is 20 characters and 
alphanumeric. 

Posted The indication of whether the Purchase Invoice is Posted or not. The 
field is a Boolean (Yes or No) indicator. 


is key to consider using smart $£ilter and $select options. 
See Part 8: Chapter 89: Performance (page 511) and Part 1: 
Chapter 2: Reading / GET (page 17) for more information. 


eo Note: With this endpoint, a large amount of data is available, so it 


Field Map 


API JSON: 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseInvoices/Sentity", 

"@odata.etag": "W/\"JzE50zMxMTg5Mjg5Mj I4NDgzNDAOODkxOzAwOyc-N"", 

"id": "d4261e29-df3a-edl1l-bbae-6045bd8e554a", 

Jiromdexese aG OOk 

WinvOLnecebDatwe ts WAOZ =O 0] 7 

IposeingDNateu a0 OEO 

Wauebate UE OH ONU 

"vendorInvoiceNumber": "107001", 


AS 
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"vendorId": "7215971e-df3a-edll-bbae-6045bd8e554a", 
"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 

"payToName": "First Up Consultants", 
"oayloconieact m RyaneMetntcoshm 

"payToVendorId": "7215971e-df3a-edll-bbae-6045bd8e554a", 
"payToVendorNumber": "20000", 

"shipToName "W 2 "W n 

snum eom tede EU 

"buyFromAddressLinel": "100 Day Drive", 
"bpuyFromAddressLine2": "", 

Hotman - Melee. 

Puy Esc mo eus vat NT] SR 

lou EE omsisat c corii 

"buyFromPostCode": "61236", 

"shipToAddressLinel": "7122 South Ashford Street", 
"shipToAddressLine2": "Westminster", 

Uisloaveocanicy we Ware Tta 

SPERO CONME y s MOS, 

"shipToState": Wi 

Ship loPos CCoden NUTS 

"payToAddressLinel": "100 Day Drive", 
"payToAddressLine2": "", 

“pa yroCrey YS Melaish rex or 

upayroC oun eya UNOS, 

UiSyetva elsi ters : WES, 

JMerenvtoletorstiE eset s MTED SU 
"shortcutDimensionlCode": "", 
"shortcutDimension2Code": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"currenecycodev: USDE, 

"orderId": "00000000-0000-0000-0000-000000000000", 
"orderNumber": "", 

"pricesIncludeTax": false, 

Ilse ounmtAmoumt 5:07 

"discountAppliedBeforeTax": true, 

"EotalAmouncExe udinglax i: SHE SE 

utora llTaxAmoume M S. Legio She 

Gtotca l Amouneme l udinolanzs Ne ET 

stacust: Paste 

MilaseModtiredDavelime mU Qo OS e 0O 


BUSINESS CENTRAL ENTITY: 
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Purchase Invoice e e [nj cea 
107209 - Fabrikam, Inc. 

Home Prepare Request Approval Invoice Actions Automate Fewer option © 
General s 
Vendor No vendorNumber Contact Krystal York 


Vendor Name 


State 

ZIP Code 
Country/Region 
Contact No 
Phone No 


Mobile Phone No 


Email 
Lines Manage 
Type No 
> Item + 1928-5 


Subtotal Excl. Tax (USD) 


inv. Discount Amount (USD) 


vendorName 


buyFromAddressLine 

buyFromAddressLine 
buyFromCity 
buyFromState 


buyFromPostCode 


buyFromCountry 
7000011 


4255550101 


e 


fabrikam.inc@contoso.com 


Line Fewer options 
Item 


Reference 


Comment 


AMSTERDAM Lamp 
214.00 
discountAmount 0.00 
0 


Document Date 


invoiceDate 
postingDate 


Posting Date 

Due Date 

Vendor Invoice No. 
Purchaser Code 

Campaign No. 

Alternate Vendor Address C 
Responsibility Center 


Assigned User ID 


Status status 
2 E 
Measure Tax Area Tax Group Line Discoun 
Quantity Code Code Code E 
5 PCS ATLANTA GA FURNITURE 


Total Excl. Tax (USD) 


Total Tax (USO! 


Total Incl. Tax (USD 
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PAGE 


Invoice Details Show less 


Currency Code Pmt. Discount Date 4/8/2022 6 
Expected Receipt Date 1/1/2021 e Tax Liable «o 
VAT Bus. Posting Group Tax Area Code ATLANTA, GA 
Vendor Posting Group DOMESTIC Tax Exemption No 
Payment Terms Code CM v Shipment Method Code 
Payment Method Code Payment Reference 
Department Code Creditor No 
Payment Discount 96 0 
Shipping and Payment ess 
Ship-to Custom Address Pay-t Custom Address 
Contact Contact No CT000011 
Phone No 4255550101 
Mobile Phone No 
Email fabrikam.inc@contoso.com 


Contact Krystal York 


IRS 1099 Code 


Remit-to Code 


Note that some fields are not available in the UI in the API, such as the orderId. 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseInvoices 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseInvoices (d4261e29-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (1 entity shown from a longer list): 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 

/APIBook/api/v2.0/S$metadata#companies ({ {companyID}})/purchaseInvoices", 
"value": [ 
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"@odata.etag": 
st hy 8 
"number": 
"invoiceDate": 
"postingDate": 
"dueDate": 


"vendorInvoiceNumber": 
"7215971e-df3a-edll-bbae-6045bd8e554a", 


"vendorId": 
"vendorNumber": 
"vendorName": 
"payToName": 
“pay rocContacti: 
"payToVendorId": 


"payToVendorNumber": 


"wn 
LÀ 


"shipToName": 
NshuploContactn: 


"buyFromAddressLinel": 
"buyFromAddressLine2": 
“Chiteagony, 


Ion Erome antes 


"buyFromCountry": 


"buyFromState": 


"buyFromPostCode": 
"shipToAddressLinel": 
"shipToAddressLine2": 
WAelantaw, 


UisilolabjeMboiCabicay eH 
NsohwpLoCoumteayi: 
"shipToState": 


"shipToPostCode": 
"payToAddressLinel": 
"payToAddressLine2": 
Wear el y 


"payToCity": 
Hav Loc omnt yA 
"payToState": 
"payToPostCode": 


"shortcutDimensionlCode": 
"shortcutDimension2Code": 


"W/N"JzE5OzMxMTg5Mjg5MjIA4NDgzNDAOODkxOzAwOyc-N"", 
"d4261e29-df3a-ed11-bbae-6045bd8e554a", 

u TOCO, 

T2 0 IE ONETO 

AO OO 

UZO LO) =O) 


LO (Oca 


ADO) 


Nnm sit Up onsudsanissq 
WEES Whe Comemibliceimnes y 


" 


Evan McIntosh", 
"7215971e-df3a-edll-bbae-6045bd8e554a", 
WZOOOO", 


woe 
, 


"100 Day Drive", 


n" 
, 


LESS 

BETIS 

UH SS 

"7122. South Ashford Street“, 
"Westminster", 


"Us" ; 


woe 
, 


Westen tus 
"100 Day Drive", 


woe 
, 


NOUIS 


WE. 


UA SGU 


"wn 
T 


"wn 
, 


"currencyId": "00000000-0000-0000-0000-000000000000", 
"currencyCode": "USD", 

"orderId": "00000000-0000-0000-0000-000000000000", 
"orderNumber": "", 

"pricesIncludeTax": false, 

"discountAmount": O0, 

"discountAppliedBeforeTax": true, 
VeoitalAmoume be usb 9o? 7S 

utora MaxAmoumnmt 4a — dig. SET 
VeovalAmouneineluda ng Tass 90^ f 

stars: Pasig: 


"lastModifiedDateTime": 


), 


/210)2:22—(0)5)—12: 5/3:80)1L 8.338 (0)9) c. MSS 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 


nies ({companyID}}) /purchaseInvoices 


Example POST Request Body: 


"invoiceDate": 


1210/2 3010) 8]— 


LGN, 
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ISOS MMe Dees WEIL G d Ou 
JWiskimsjbisue eia POESIE SU 
"vendorNumber": "20000", 
"currencyCode": "EUR", 
"pricesIncludeTax": true 


Example POST Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/purchaseInvoices/Sentity", 
"Qodata.etag": "W/\"JzE50z1I3NzE50DI ONDcwOTI1Mjk5MDUxOzAwOyc=\"", 
Wid a5 9959t- 255 eciii c6 90/05 9alàdc6 
Uiguiniceset es Wil) qq AW 
WAM VOneeD awe 09 9 Se. 
JheroyenesusweDeuee g VO (d uL 
"dueDateV: "2021-09-15, 
"vendorInvoiceNumber": "", 
"vendorId": "7215971e-df3a-edll-bbae-6045bd8e554a", 
"vendorNumber": "20000", 
"vendorName": "First Up Consultants", 
"payToName": "First Up Consultants", 
"payloGontbactv Evan Merntosha, 
"payToVendorId": "7215971e-df3a-edl1-bbae-6045bd8e554a", 
"payToVendorNumber": "20000", 
"shupToName"w: "\CRONUS USA, Inet, 
LiginajevkoCemeaioir ys WU. 
"buyFromAddressLinel": "100 Day Drive", 
"buyFromAddressLine2": "", 
Mowiyidiaoiesicyy 9 Welmiezieo 
Mbuy a romCounery' 2 “US, 
MUR EOmMsizaeewwss «TEY, 
"UouvyEromPostcode": 6123969 
"shipToAddressLinel": "7122 South Ashford Street", 
"shipToAddressLine2": "Westminster", 
tshi phoentyt Atlanta, 
Ushio Lo Conner yo ASA 
WshiplLosizatsel > WT 
I shprnoebosiseodeoen qa 
"payToAddressLinel": "100 Day Drive", 
"payToAddressLine2": "", 
hereto eate e. ela Xe on 
Hay LOC OUMte ayia ome, 
Wan else ES : UE 
Ioomweloboste oco IN 
"shortcutDimensionlCode": "", 
"shortcutDimension2Code": "", 
"currencyId": "8414971e-df3a-edl11-bbae-6045bd8e554a", 
"currencyCode": "EUR", 
"orderId": "00000000-0000-0000-0000-000000000000", 
"orderNumber": "", 
"pricesIncludeTax": true, 
"discountAmount": O0, 
"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 
Into tau ccAImoun t: OF 
"totalAmountIncludingTax": 0, 
isherhebisy ue: Wiphecneett 
WiasteModiEredDaveLimet.. 2022 lO) 752i IG fp C 
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PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]]))/purchaseInvoices (b5f4993f-2d55-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


Melee sg W022i (0 7 


"vendorNumber": "10000", 
"discountAppliedBeforeTax": true, 
UcunsmeneweoccM WISI 


"pricesIncludeTax": false 


Example PATCH Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/purchaseInvoices/Sentity", 
"Qodata.etag": "W/N"JzE5OzQOzNzYzMTY5MDk1MTk20DAzMDMxOzAwOyc-N"", 
Nardi HosA Orsi- 285/55: cilii 9e9/6-90/03/ 9219666 
vnumoe ras Wab@ 2a au, 
"invoiceDate": "2021-08-16", 
Vpositing Date M B. MAN 0)2 TE (OTI E n 
Vawebare T202 21E 20u, 
"vendorInvoiceNumber": "", 
"vendorId": "711597le-df3a-ed1ll1l-bbae-6045bd8e554a", 
"vendorNumber": "10000", 
"vendorName": "Fabrikam, Inc.", 
"payToName": "Fabrikam, Inc.", 
pay LOC conica Esse Ys Ww 
"payToVendorId": "7115971e-df3a-edll-bbae-6045bd8e554a", 
"payToVendorNumber": "10000", 
UshaptoName uk “CRONUS! USA, ncm 
snum onse ds WU 
"buyFromAddressLinel": "10 North Lake Avenue", 
"buyFromAddressLine2": "", 
MepyaeomlGsiew se Mire Ieee, 
uy brome euntes vat: TT S 
"buyFromState": "GA", 
NipuyEromeostcode m STU 
"shipToAddressLinel": "7122 South Ashford Street", 
"shipToAddressLine2": "Westminster", 
Nis tyagomo esty Ate ata 
Weslatayjoytecroruimterey s. Mage, 
eimstioMM ese S TUE 
oship lopos teodenn EE 
"payToAddressLinel": "10 North Lake Avenue", 
"payToAddressLine2": "", 
MW DayzLO sea MOI A tlteun al, 
Spay oCouünt ryn US. 
"payToState" : "GA", 
UoewiboPostocdem ED 
"shortcutDimensionlCode": "", 
"shortcutDimension2Code": "", 
"currencyId": "00000000-0000-0000-0000-000000000000", 
Ucunsrencvye ode USIMM 
"orderId": "00000000-0000-0000-0000-000000000000", 
"orderNumber": "", 
"pricesIncludeTax": false, ) 
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"discountAmount": O0, 

"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 

"ntio;ba Das Amount: 07 

"totalAmountIncludingTax": 0, 

Wieneeiebisis DEAE, 

MiaseModuiredDawelime a2 02207 onl B Sie (0) dL O4 Sp 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseInvoices (b5f4993f-2d55-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


From the Purchase Invoices list, click on the New button in the Action Bar. 


Purchase Invoices: All v PD Search -F New [iil Delete [2 Release | v [i Post | v 


Buy-from Vendor 
Vendor No. Buy-from Vendor Name Invoice No. Location Code 


10000 Fabrikam, Inc. 107209 
107210 20000 First Up Consultants 107210 
107211 30000 Graphic Design Institute 107211 


107212 10000 Fabrikam, Inc. 9001 


This will open a blank Purchase Invoice card. Select a Customer, which should 
automatically assign a Purchase Invoice No. 
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Purchase Invoice 


Home Prepare Request Approval Invoice 


af Post v [2 Release v 
General 


Vendor Name 
Contact 


Posting Date 


More options 


Due Date 
Vendor Invoice No. 


Status 


Lines Manage Line Fewer options 


Cost Excl. Tax Code 


Filling out a Purchase Invoice is beyond the scope of this book, but this method creates 
it enough to be available for the API. 


UPDATING 


Change a field in the General section, such as the Due Date. 


DELETING 


An unposted Purchase Invoice can simply be deleted via the Delete action in the Action 
Bar. Posted Purchase Invoices might be able to be deleted, but that depends on system 
configuration. 


Bound Actions 


e Post 


e vendors (page 291) 

e countryRegion (page 402) 

e currencies (page 407) 

e purchaselnvoiceLines (page 261) 
e pdfDocument (page 450) 

e attachments (page 378) 

e dimensionSetLines (page 427) 


| Version 
19.0 


Changes 


Added Dimension fields to the API. 


18.0 


Added Order fields. 
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Chapter 46: Purchase Invoice Lines 


The Purchase Invoice Lines endpoint allows access to both Purchase Invoice Lines and 
Posted Purchase Invoice Lines. When working with this endpoint, it is strongly recommended 
to read Part 8: Chapter 88: Sales & Purchase Documents (page 506). 


Primary Key 


Document Id The generated identifier for the Purchase Invoice Line is created and 
used under the hood by Business Central to perfectly separate and 
identify. The field is a GUID. It is locked and managed by BC. 
Line No. The numeric identifier for the specific Purchase Invoice Line. It is unique 
only in the given Sales Invoice. Integer Identifier. 

Note that this is an aggregate table, so it often comes from a Document Line table with 
a primary key of Document No. and Line No., but the aggregate table uses the Document Id 
to ensure uniqueness. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseInvoices (b5f4993f- 
2d55-ed11-8c36-000d3a8dc661) /purchaseInvoiceLines/Sentity", 

"@odata.etag": "W/\"JzE50zE2NDM4Njg2NTM2MTI5MjMzNTAxOzAwOyc=\"", 

Wig se 9ra998—3255-ed lal ses o-O00dsacgdecoi, 

“documentid™: "b5f4993ft-2d55-edi11-86€36-000d3a8dc661"'7 

"sequence": 10000, 

"itemId": "7615971e-df3a-edll-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1896-S", 

"description": "ATHENS Desk", 

"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 


"unitOfMeasureCode": "PCS", 
Wipinaiecosiel s eg cq. 


B germ 
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Mica iesintey B A 

"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
amount Exe ludingtaxs 8. 0), 

aranc ode IEUENIUHUBUERBS 

"taxPercent": 5.99974, 

"totalTaxAmount": 0, 

Camounmt ne bell etes e. (0r 

gums esencia 

"netAmount": 1561.4, 

"netTaxAmount": 93.68, 

"netAmountIncludingTax": 1655.08, 
"expectedReceiptDate": "2021-08-16", 
"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


BUSINESS CENTRAL ENTITY: 


Purchase Ir E 


107209 - Fabrikam, Inc. 


Home Prepare Request Approval invoice Actions Automate 
General 


Vendor Name Fabrikam. Inc. 4/30/2022 


Contact Vendo Invoice b 07209 


Descrpbon/Commert 


AMSTERDAM Lamp 2 42.80 ATLANTA.GA FURNITURE 


Subtotal Excl. Tax (USD) Total Excl. Tax (USD) 
Inv. Discount Amount (USD) : Total Tax (USD) 


Invoice Discount % Total Inci. Tax (USD) 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/purchaseInvoices (b5f4993f-2d55-ed11-8c36- 
000d3a8dc661) /purchaseInvoiceLines 


Example GET Request URI Single: 
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https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseInvoices (b5f4993f-2d55-ed11-8c36- 
000d3a8dc661) /purchaseInvoiceLines (3c9fa998-3255-ed11-8c36-000d3a8dc661) 


Example GET Request URI Single (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseInvoiceLines (3c9fa998-3255-ed11-8c36-000d3a8dc661) 


Example GET Response (1 entity shown from a longer list): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseInvoices (b5f4993f- 
2d55-ed11-8c36-000d3a8dc661) /purchaseInvoiceLines", 

"value": [ 


{ 


"@odata.etag": "W/\"JzE50zE2NDM4Njg2NTM2MTI5MjMzNTAxOzAwOyc=\"", 
Wici Werbespots Hb dites OW Orel sarstolo@oil Vp 

"documentId": "b5f4993f-2d55-ed11-8c36-000d3a8dc661", 
"sequence": 10000, 

"itemId": "7615971e-df3a-edl1l-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1896-S", 

"description": "ATHENS Desk", 

"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 

Mant ECOSSE B. THX) 


Wigibiciaiciniew B y, 

"discountAmount": O0, 

"discountPercent": O0, 

"discountAppliedBeforeTax": false, 
"amountExcludingTax": 0, 

"taxCode": "FURNITURE", 

"taxPercent": 5.99974, 

"totalTaxAmount": O0, 

"amountIncludingTax": 0, 
"invoiceDiscountAllocation": 0, 

"netAmount": 1561.4, 

"netTaxAmount": 93.68, 

"netAmountIncludingTax": 1655.08, 
"expectedReceiptDate": "2021-08-16", 
"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


}, 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/purchaseInvoices (b5f4993f-2d55-ed11-8c36- 
000d3a8dc661) /purchaseInvoiceLines 


Example POST Request Body: 


"lineType": "Item", 
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"lineObjectNumber": "1900-S", 
JienpieuanEabipy/ sae 4 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/S$metadata#companies (( (companyID])) /purchaseInvoices (b5f4993f- 
2d55-ed11-8c36-000d3a8dc661) /purchaseInvoiceLines/Sentity", 

"@odata.etag": "W/\"JzIwOzEyODY4MjM4MDUIMzk3NDc2MDg3MTswMDsn\"", 

"id": "e58edbe6-3755-ed11-8c36-000d3a8dc661", 

"documentId": "b5f4993f-2d55-ed11-8c36-000d3a8dc661", 

"sequence": 20000, 

"itemId": "7715971e-df3a-ed11-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 

"description": "PARIS Guest Chair, black", 
"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


HU rotae roysuet p TESI) Sh, 

Weibereticaiey B "y 

"discountAmount": O0, 

"discountPercent": 0, 

"discountAppliedBeforeTax": false, 
"amountExcludingTax": 0, 

Itera oce IVEUTEINIEDUE 

"taxPercent": 6.00133, 

"totalTaxAmount": 0, 

“amount lne ludinotaxs 0 
"invoiceDiscountAllocation": 0, 

"netAmount": 601.2, 

"netTaxAmount": 36.08, 

"netAmountIncludingTax": 637.28, 
"expectedReceiptDate": "2021-08-16", 
"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseInvoices (b5f4993f-2d55-ed11-8c36- 
000d3a8dc661) /purchaseInvoiceLines (e58edbe6-3755-ed11-8c36-000d3a8dc661) 


Example PATCH Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseInvoiceLines (e58edbe6-3755-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


"iemesenEdLEN/ ^ B. Biy 
"discountPercent": 25 
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Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseInvoices (b5f4993f- 
2d55-ed11-8c36-000d3a8dc661) /purchaseInvoiceLines/Sentity", 

"Qodata.etag": "W/N"JzIWOZzEXxODOzNTOS5NDIOMzEyNTk1ODE3MTswMDsnN"", 

"id": "e58edbe6-3755-ed11-8c36-000d3a8dc661", 

"documentId": "b5f4993f-2d55-ed11-8c36-000d3a8dc661", 

"sequence": 20000, 

"itemId": "7715971e-df3a-edl1-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 

"description m iere expres Charb, Blacki 
"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


U'owbw(eoxsuE 5 30.5 

"enia enan a 18), 

I'a'seount Amount 5500567 

udiscountPercen i: 25, 

"discountAppliedBeforeTax": false, 
"amountExcludingTax": 0, 

"taxCode": "FURNITURE", 

"taxPercent': 6.00022, 

VEOtallaxAmnount: OF 

Wamount Dneluding tax) 0), 
"invoiceDiscountAllocation": 0, 

"netAmount": 901.8, 

metlaxAmount™:; 547117 

InecAmountineludingkraxs Oooo 
"expectedReceiptDate": "2021-08-16", 
"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseInvoices (b5f4993f-2d55-ed11-8c36- 
000d3a8dc661) /purchaseInvoiceLines (e58edbe6-3755-ed11-8c36-000d3a8dc661) 


Example DELETE Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/purchaseInvoiceLines (e58edbe6-3755-ed11-8c36-00083a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 
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CREATING 


Unposted Purchase Invoice Lines can be created manually, though the particulars of 
creating Purchase Invoices are beyond this book. If the line has some information populated, 
it should be available via the API. 


UPDATING 


Adjusting any field on an unposted Purchase Invoice Line, such as the Description, will 
update the line. 


DELETING 


Any unposted Purchase Invoice Line may be deleted, though some business restrictions 
may prevent removal. 


Bound Actions 


No bound actions. 


e purchaselnvoices (page 252) 
e items (page 323) 

e accounts (page 38) 

e unitsOfMeasure (page 471) 

e itemVariants (page 339) 

e dimensionSetLines (page 427) 


Changes 
Fields Added: description2 


Some tax fields made non-editable. 
Added Location. 
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Chapter 47: Purchase Orders 


The Purchase Orders endpoint allows access to Purchase Order documents. When 
working with this endpoint, it is strongly recommended to read Part 8: Chapter 88: Sales & 
Purchase Documents (page 506). 


Note: With this endpoint, a large amount of data is available, so it 
is key to consider using smart $£ilter and $select options. 
See Part 8: Chapter 89: Performance (page 511) and Part 1: 
Chapter 2: Reading / GET (page 17) for more information. 


Primary Key 


No. The identifier of the Purchase Order. The field is 20 characters and 
alphanumeric. 


Field Map 


API JsoN: 


1 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseOrders/Sentity", 
"Qodata.etag": "W/N"JzES5Ozg2NDU5NjIzMDk5NjgOMzEzNzAxOzAwOyc-N"", 
"id": "ec69e818-3255-ed11-8c36-000483a8dc661", 
"number": "106006", 
NondenDatben s. 20022 —(0y2— T qn 
JeyoxeEsuekelDeuEis 9 PNE (Qui 1 T UL 
"vendorId": "7515971e-df3a-edll-bbae-6045bd8e554a", 
"vendorNumber": "50000", 
"vendorName": "Nod Publishers", 
"payToName": "Nod Publishers", 
"payToVendorId": "7515971e-df3a-edll-bbae-6045bd8e554a", 
"payToVendorNumber": "50000", 
"shipToName": "CRONUS USA, Inc.", 
Visine tocoiminercis ie UM 
"puyFromAddressLinel": "172 Field Green", 
"buyFromAddressLine2": "", 
Vou Edom toy Ae lane, 
Voy Rome omnts NEU SU 
"buyEromsitateV: "GA 
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VipUVErOmeositce ode al Sally an), 

"payToAddressLinel": "172 Field Green", 
"payToAddressLine2": "", 

JhsreNAEOXO tie Mer ne bamean, 

pay LOC OU tea S. MUS A 

"payToState" : UGAN 

Jhon sg WS eu 

"shipToAddressLinel": "7122 South Ashford Street", 
"shipToAddressLine2": "Westminster", 

"shupmnocdstym i “Atlanta, 

S PEPROCOUMECY a Moissy, 

Usinanoltoysiecheey! a MUI 

shsprnobosiseoco MENU 

"shortcutDimensionlCode": "", 
"shortcutDimension2Code": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"currenecyecodes USD 

"pricesIncludeTax": false, 

"paymentTermsId": "8114971e-df3a-edl1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
WT oiolieielnvsysyerelie WW. 

"requestedReceiptDate": "0001-01-01", 
MGhi@secoumeAMoumMitet ge (0). 

"discountAppliedBeforeTax": true, 
"totalAmountExcludingTax": 780.7, 

"totalTaxAmount": 46.84, 

"totalAmountIncludingTax": 827.54, 

"fullyReceived": true, 

Wisheeheibisys DCA mee! p 

NrastsMocusstedibatenmeu:U2022- 0 0- 70/2 ::9] 5] 9 92/97 


BUSINESS CENTRAL ENTITY: 
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[ci] 
Q 
g^ 


106001 - Fabrikam, Inc. 


Home Prepare  Print/Send Request Approval ^ Order More options © 
General Show less 
Vendor No. Document Date 4/8/2022 

Vendor Name Posting Date 
Buy-from Due Date 4/30/2022 

Address Vendor Invoice No 5755 

City No. of Archived Versions 0 
State Order Date 4/8/2022 

ZIP Code Quote No. 

Country/Region Vendor Order No 

Contact No CT000011 Vendor Shipment No 

Phone No. Alternate Vendor Address 


Mobile Phone No Responsibility Center 


Email fabrikam.inc@contoso.com Assigned User ID 
Contact Krystal York Status status 
Lines Manage Line Functions Order Fewer options 2 E 
Item Unit of Direct Unit 
Reference Location Bin Reserved Measure Cost Excl Tax Area Tax Group 
Type No. No Description Code Code Quantity Quantity Code Tax Code Code 
> Item * 1896-8 ATHENS.Desk ri = AS 780.70 ATLANTA.GA FURNITURE 
‘ + 


Subtotal Excl. Tax (USD) 5,464.90 Total Excl. Tax (USD) totalAmountExcludingTax 
Inv. Discount Amount (USD) discountAmount 0.00 Total Tax (USD) totalTaxAmount 
Invoice Discount % 0 Total Incl. Tax (USD) totalàmountIncludingTax 
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Invoice Details 


Currency Code currencyCode Tax Area Code ATLANTA GA 
Expected Receipt Date 4/9/2022 Tax Exemption No. 

VAT Bus. Posting Group Shipment Method Code 

Vendor Posting Group Payment Reference 

Payment Terms Code Creditor No 

Payment Method Code On Hold 


Department Code ishortcutDimensionlCode Inbound Whse. Handling 


Customergroup Code shortcutDimension2Code Lead Time Calculation 


Payment Discount % Requested Receipt Date 
Pmt. Discount Date Promised Receipt Date 


Tax Liable IRS 1099 Code 


Shipping and Payment 


Ship-to [Custom Address Pay-to [Custom Address 

Name shipToName Name payToName 
Address shipToAddressLinel Address 

Address 2 shipToAddressLine2 Address 2 

City shipToCit City 

State shipToState State 

ZIP Code shipToPostCode ZIP Code 

Country/Region shipToCountr Country/Region 


Contact shipToContact Contact No. 


Contact 


Phone No. 


Mobile Phone No. 


Email fabrikam.inc@contoso.com 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrders 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrders (ec69e818-3255-ed11-8c36-000d3a8dc661) 


Example GET Response (entities shown from a longer list): 
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{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseOrders", 

"value": [ 


{ 


"@odata.etag": "W/\"JzE50zg2NDU5Nj 1zMDk5Njg0MzEzNzAxOzAwOyc=\"", 
udun weCoVeGls=s255-edll=ses os -000dsasdecoi, 
"number": "106006", 

WonderDatel | !2022 04-1, 

"reroxeiedustebeue m UON Eas Wr 

"vendorId": "7515971e-df3a-edll-bbae-6045bd8e554a", 
"vendorNumber": "50000", 

"vendorName": "Nod Publishers", 

"payToName": "Nod Publishers", 

"payToVendorId": "7515971e-df3a-edll-bbae-6045bd8e554a", 
"payToVendorNumber": "50000", 

VohmpLoNamet-  GRONUSs USA I CU 

Wislnakoitocomrciete B. WM. 

"bpuyFromAddressLinel": "172 Field Green", 
"buyFromAddressLine2": "", 

Ulo Edom dte 2 Wc Iker 

Moby elon nie obo oues B. MOIS 

"buyFromState": "GA", 

Muy bromeosizCodel SES 

"payToAddressLinel": "172 Field Green", 
"payToAddressLine2": "", 

oae GE ig WANE ileinecit 

Hay LOC OU rye: USUS 


"payToState" : TUGAN 

tpayropos teodenn s WS y e 

"shipToAddressLinel": "7122 South Ashford Street", 
"shipToAddressLine2": "Westminster", 


Uship le cds van Atta 

WisinaketoCroimeey e n MAUS 

ish idostaicel M 

Sohne lopos CCOdeni TN 

"shortcutDimensionlCode": "", 
"shortcutDimension2Code": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"curnenecytodes VUS DIM, 

"pricesIncludeTax": false, 

"paymentTermsId": "8114971le-df3a-edl1l-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
“purchasers: WW 

"requestedReceiptDate": "0001-01-01", 
VGhiseoumeAM@ uit M S Ol 

"discountAppliedBeforeTax": true, 
"totalAmountExcludingTax": 780.7, 

"totalTaxAmount": 46.84, 

"totalAmountIncludingTax": 827.54, 

"fullyReceived": true, 

Wcienebis| S. S Dra EEN, 

WMiastModa filed Dake lime 2 022 — MOTAS 


}, 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/purchaseOrders 
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Example POST Request Body: 


VOOst lng Datel m2 02 2 (toj Note, 
"vendorNumber": "20000", 
Weurnencycode | SEURAT 


"pricesIncludeTax": true 


Example POST Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/purchaseOrders/Sentity", 
"Qodata.etag": "W/\"JzE50zI 40DI yODUOODI zMDQ4Mj UyODI xOzAwOyc=\"", 
Mid “oedooa44—sdoo-edi 9e906-00/06898!9clc06/19 


"number": "106007", 
VordexrDate:) "2022-0 —2i6, 
VASO DeEa B 2/0272 (0 6) — TL (Sr 


"vendorId": "7215971e-df3a-edll-bbae-6045bd8e554a", 
"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 

"payToName": "First Up Consultants", 

"payToVendorId": "7215971e-df3a-edll-bbae-6045bd8e554a", 
"payToVendorNumber": "20000", 

"shipToName": "CRONUS USA, Inc.", 

Wisioaieitoceiminereis S UM 

"buyFromAddressLinel": "100 Day Drive", 
"buyFromAddressLine2": "", 

ow Esomesitsyl Met siae 

IPIowyiBrsome onte MOIS!" 5 

WOU LOM sizaiteeuns ENT 

"buyFromPostCode": "61236", 

"payToAddressLinel": "100 Day Drive", 
"payToAddressLine2": "", 

Jerez e elei Xe on 

io aoo ume cv EUST 

Uey rogtate : Un. 

InoaweBoEoste oco ME IU 

"shipToAddressLinel": "7122 South Ashford Street", 
"shipToAddressLine2": "Westminster", 

vshiphocitye T Wave ikeyeiec 7 

WislsutjsyeXeroxsünteses s Moissy, 

Nichitip Mo Siteatzety m MU 

ship orEosise oom USTED 

"shortcutDimensionlCode": "", 

"shortcutDimension2Code": "", 

"currencyId": "8414971e-df3a-edll-bbae-6045bd8e554a", 
"currencyCode": "EUR", 

"pricesIncludeTax": true, 

"paymentTermsId": "8114971e-df3a-edll-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
“purchasers. WW. 

"requestedReceiptDate": "0001-01-01", 

"discountAmount": O0, 

"discountAppliedBeforeTax": false, 
"totalAmountExcludingTax": 0, 

GtotalTaxAmountu: n0 
"totalAmountIncludingTax": 0, 

"fullyReceived": false, 

Sedis Ea E 

"lastModifiedDateTime": "2022-10-26T14:48:35.8572" 
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PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrders (68d65a44-3d55-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


WisVOsiealiac Deca S UA S24 
"vendorNumber": "20000", 
veurrencycodet USE 


Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/$metadata#companies ({{companyID}})/purchaseOrders/Sentity", 

"Qodata.etag": "W/\"JzE50zUyODUZNDg30Tc3NTkyMTQ2NzkxOzAwOyc=\"", 

"id": "68d65a44-3d55-ed11-8c36-000d3a8dc661", 

number "=: 1096007 

WorderDate = "2022-10-26, 

WeOsiedmeDere! 3 "21092: 5110) 22 OW 7 

"vendorId": "7215971e-df3a-ed11-bbae-6045bd8e554a", 


"vendorNumber": "20000", 

"vendorName": "First Up Consultants", 
"payToName": "First Up Consultants", 
"payToVendorId": "7215971e-df3a-edll-bbae-6045bd8e554a", 
"payToVendorNumber": "20000", 
"shipToName": "CRONUS USA, Inc.", 
snum Imo comis U 
"buyFromAddressLinel": "100 Day Drive", 
"buyFromAddressLine2": "", 

iow Ersomesie yl NS beo 
EPUVECOMCOUNCEYV A: SI 

SDUVEroMS tacens WIL, 
MDUVErOmPostCodel:s Gil 2 36 
"payToAddressLinel": "100 Day Drive", 
"payToAddressLine2": "", 


Span abips7 s B. MOI 

Spay LOC ouniEmy IUS, 

upaylootate p. MILI 

"payToPostCode": "61236", 

"shipToAddressLinel": "7122 South Ashford Street", 
"shipToAddressLine2": "Westminster", 

WelmasWmexeunw; wg Wave llerace, 

Ushio lo COMET yae Meu 

"shipToState": Uu. 

I shpnoebosiseocden T 

"shortcutDimensionlCode": "", 

"shortcutDimension2Code": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
"currencyCode": "USD", 

"pricesIncludeTax": true, 

"paymentTermsId": "8114971e-df3a-edl1-bbae-6045bd8e554a", 
"shipmentMethodId": "00000000-0000-0000-0000-000000000000", 
“purchaser; uw 

"requestedReceiptDate": "0001-01-01", 

WiGhi#seoumeAmoumitsls: 0, 

"discountAppliedBeforeTax": false, 

toca Amouncixe l udingmaxs: Mor ) 
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"totalTaxAmount": O, 

Grota Amoune me ucdinotaxs P 

"fullyReceived": false, 

Mcneehe piss t; WDrca ked, 

"lastModifiedDateTime": "2022-10-26T14:50:49.693Z" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/purchaseOrders (68d65a44-3d55-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


From the Purchase Orders list, click on the New button in the Action Bar. 


Purchase Orders: v J Search + New W Delete Process v [2 Release | v Bf Post. | v Prin 


Vendor 

Buy-from Authorizati Assigned User Document 
No, t Vendor No. Buy-from Vendor Name No. Location Code ID Date 
106001 : Fabrikam, Inc. 4/8/2022 
106002 First Up Consultants 4/9/2022 
106003 Wide World Importers 4/13/2022 
106004 Graphic Design Institute 5/1/2022 
106005 Nod Publishers 4/11/2022 


106006 Nod Publishers 4/11/2022 


This will open a blank Purchase Order card. Select a Vendor, which should automatically 
assign a Purchase Order No. 


Purchase Order 


Home Prepare  Print/Send Request Approval Order More options 


lif Post.. | v [2 Release v fils Create Whse. Receipt  [ Create Inventory Put-away/Pick.. [à Send Intercompany Purchase Order — Arci 
General 


Vendor Name -€ Vendor Invoice No. 


Contact Vendor Shipment No. 


Document Date Status 


Lines Manage Line Functions Order Fewer options 
ltem 
Reference. 

Type No ^ 


> iten 


enough to be available for the API. 
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UPDATING 


Change a field in the General section, such as the Due Date. 


DELETING 


An unposted Purchase Order can simply be deleted via the Delete action in the Action 
Bar. If it has been posted partially (shipped, invoiced, etc.), it might not be possible to delete 
the Purchase Order in progress. 


Bound Actions 


e RecieveAndInvoice 


e vendors (page 291) 

e countryRegion (page 402) 

e currencies (page 407) 

e paymentTerms (page 445) 

e shipmentMethods (page 457) 

e purchaseOrderLines (page 276) 

e attachments (page 378) 
dimensionSetLines (page 427) 


History 


| Version Changes 
19.0 Added Dimension fields to the API 
18.0 Added. 
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Chapter 48: Purchase Order Lines 


The Purchase Order Lines endpoint allows access to Purchase Order Lines. When 
working with this endpoint, it is strongly recommended to read Part 8: Chapter 88: Sales & 
Purchase Documents (page 506). 


Primary Key 


Document Id The generated identifier for the Purchase Order Line is created and used 
under the hood by Business Central to perfectly separate and identify. 
The field is a GUID. It is locked and managed by BC. 
Line No. The numeric identifier for the specific Purchase Order Line. It is unique 
only in the given Purchase Order. Integer Identifier. 

Note that this is an aggregate table, so it often comes from a Document Line table with 
a primary key of Document No. and Line No., but the aggregate table uses the Document Id 
to ensure uniqueness. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseOrders (68d65a44- 
3d55-ed11-8c36-000d3a8dc661) /purchaseOrderLines/Sentity", 

"Qodata.etag": "W/\"JzIwOzE1LODM3MTE5MTAONzQzZNzYONDA3MTswMDsn\"", 

"id": "a5a4525e-3e55-ed11-8c36-000d3a8dc661", 

"documentId": "68d65a44-3d55-ed11-8c36-000d3a8dc661", 

"sequence": 10000, 

"itemId": "7715971e-df3a-edl1l-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 

ickepiexeijoesioinl m iere exces Chart Placki 
"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


JewyeWWdEaLib S 19 

Micicec tUnat Cost) 50S, 
"discountAmount": O0, 
"discountPercent": 0, 
"discountAppliedBeforeTax": false, 
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"amountExcludingTax": 1134.34, 

Vice iCoclas Mis 7 

"taxPercent": 5.99996, 

"totalTaxAmount": 68.06, 

VaMounelneLudaimng lass 22 
"invoiceDiscountAllocation": O0, 

WnetAmount tcd 94 34 

"netTaxAmount": 68.06, 

"netAmountIncludingTax": 1202.4, 
"expectedReceiptDate": "2022-10-27", 
"receivedQuantity": 0, 

"invoicedQuantity": O0, 

"invoiceQuantity": 8, 

"receiveQuantity": 8, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


BUSINESS CENTRAL ENTITY: 


hase Orde 


6001 - Fabrikam, Inc. 


10 


Home Prepare Print/Send Request Approval Order 
General 


Fabrikam. Inc. 


Fewer options 
Location Bin Reserved — Measur tE Tax Grox ne Amount 
Code Code Quantity Quantity Code x Code Code Excl. Tax 


ATHENS Desk 780.70 ATLANTA.GA FURNITURE 5,464.90 


Subtotal Excl. Tax (USD) l fotal Excl. Tax (USD 5,464.90 
Inv. Discount Amount (USD) T otal Tax (US 327.89 


Invoice Discount 96 fotal Incl. Tax (USD) 5,792.79 


4/9/2022 4/9/2022 
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GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrders (9305b746-a6c7-ecl1-bb8d- 
000d3a392£79) /purchaseOrderLines 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrders (68d65a44-3d55-ed11-8c36- 
000d3a8dc661) /purchaseOrderLines (a5a4525e-3e55-ed11-8c36-000d3a8dc661) 


Example GET Request URI Single (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrderLines (a5a4525e-3e55-ed11-8c36-000d3a8dc661) 


Example GET Response (1 entity shown from a longer list): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseOrders (68d65a44- 
3d55-ed11-8c36-000d3a8dc661) /purchaseOrderLines", 

"value": [ 


{ 


"Qodata.etag": "W/\"JzIwOzE1LODM3MTE5MTAONzQzZNzYONDA3MTswMDsn\"", 
"id": "a5a4525e-3e55-ed11-8c36-000d3a8dc661", 

"documentId": "68d65a44-3d55-ed11-8c36-000d3a8dc661", 
"sequence": 10000, 

"itemId": "7715971e-df3a-edl1-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 

"description"; "PARTS Guest Chair, black", 
"unitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


“ouant eys 19 

WieliiqeciclUimuinicicosie ls ISO), Si, 
"discountAmount": O0, 
"discountPercent": 0, 
"discountAppliedBeforeTax": false, 
"amountExcludingTax": 1134.34, 

tace occ MUEWENIIUDERBM 
"taxPercent":; 5.99996, 
"totalTaxAmount": 68.06, 
"amountIncludingTax": 1202.4, 
"invoiceDiscountAllocation": 0, 
"netAmount": 1134.34, 
"netTaxAmount": 68.06, 
"netAmountIncludingTax": 1202.4, 
"expectedReceiptDate": "2022-10-27", 
"receivedQuantity": 0, 
vinvonrcedouanti eya NO 
"invoiceQuantity": 8, 
"receiveQuantity": 8, 
"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 


), 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrders (68d65a44-3d55-ed11-8c36- 
000d3a8dc661) /purchaseOrderLines 


Example POST Request Body: 


"lineType": "Item", 
"lineObjectNumber": "2000-S", 
"quantity": 4 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseOrders (68d65a44- 
3d55-ed11-8c36-000d3a8dc661) /purchaseOrderLines/Sentity", 

"@odata.etag": "W/\"JzIwOzExNzk2NjczMDg40TM5Mj I5ODEOMTswMDsn\"", 

"id": "3b1682c1-3e55-ed11-8c36-000d3a8dc661", 

"documentId": "68d65a44-3d55-ed11-8c36-000d3a8dc661", 

"sequence": 20000, 

"itemId": "8915971e-df3a-edl1-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chair, green", 
"unitOfMeasureId": "e415971e-df3a-edl1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


Weibieieicaiey M S Ay 

Wels eres) meste S osten IPTE, 
VGhi@sCoumeAM@ Umit: am Ol 
"discountPercent": 0, 
"discountAppliedBeforeTax": false, 
WamountexelucungLax'! 558 99 

tace occ UP URINTEL URE, 

Wid Pere eintat ass oreo oo Gila, 

VEO toot cmo: SoD), 
"amountIncludingTax": 592.4, 
"invoiceDiscountAllocation": 0, 
"netAmount": 558.87, 

"netTaxAmount": 33.53, 
"netAmountIncludingTax": 592.4, 
"expectedReceiptDate": "2022-10-27", 
"receivedQuantity": 0, 

gione anus Or 
"invoiceQuantity": 4, 
"receiveQuantity": 4, 
"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 
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PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrders (68d65a44-3d55-ed11-8c36- 
000d3a8dc661) /purchaseOrderLines (3b1682c1-3e55-ed11-8c36-000d3a8dc661) 


Example PATCH Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/purchaseOrderLines (3b1682c1-3e55-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

Weitere Bi 

"discountPercent": 10, 

"description": "SYDNEY Swivel Chairs, Green, for dining area" 


Example PATCH Response: 


{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseOrders (68d65a44- 
3d55-ed11-8c36-000d3a8dc661) /purchaseOrderLines/Sentity", 

"@odata.etag": "W/\"JzIwOzExODEZMDkwNzI2Nzk2MzMwOTkSMTswMDsn\"", 

nid" “Sbilleszcl—se55-edll—Sese-000dsasde6ol, 

"documentId": "68d65a44-3d55-ed11-8c36-000d3a8dc661", 

"sequence": 20000, 

"itemId": "8915971e-df3a-edll1-bbae-6045bd8e554a", 

"accountId": "00000000-0000-0000-0000-000000000000", 


"lineType": "Item", 

"lineObjectNumber": "2000-S", 

"description": "SYDNEY Swivel Chairs, Green, for dining area", 
"unitOfMeasureId"; "e415971e-df3a-edl1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "PCS", 


touan eya: 13i 
Wiehe EU nentaC osetia ale, 
"discountAmount": 118.48, 
"discountPercent": 10, 
"discountAppliedBeforeTax": false, 

XU mente Bios luc imclas' TIO SOT 

"taxcodew “FURNITURE, 

"taxPercent": 6.00024, 

"totalTaxAmount": 60.36, 

Wamount bred ur elusmos 110/666 S32 
"invoiceDiscountAllocation": 0, 

"netAmount": 1005.96, 

"netTaxAmount": 60.36, 

"netAmountIncludingTax": 1066.32, 

"expectedReceiptDate": "2022-10-27", 

"receivedQuantity": 0, 

invoncedouanmti eys- 07 

"invoiceQuantity": 8, 

"receiveQuantity": 8, 

"itemVariantId": "00000000-0000-0000-0000-000000000000", 
"locationId": "00000000-0000-0000-0000-000000000000" 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrders (68d65a44-3d55-ed11-8c36- 
000d3a8dc661) /purchaseOrderLines (3b1682c1-3e55-ed11-8c36-000d3a8dc661) 


Example DELETE Request URI (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseOrderLines (3b1682c1-3e55-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


Purchase Order Lines can be created manually, though the particulars of creating 
Purchase Orders are beyond the scope of this book. If the line has some information populated, 
it should be available via the API. 


UPDATING 
Adjusting any field on an unposted Purchase Order Line, such as the Description, will 
update the line. 
DELETING 


Any unposted Purchase Order Line may be deleted, though some business restrictions 
may prevent removal. If it has been posted partially (shipped, invoiced, etc.), it might not be 
possible to delete the Purchase Order Line in progress. 


Bound Actions 


No bound actions. 
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Navigations 


purchaseOrders (page 267) 
items (page 323) 

accounts (page 38) 
unitsOfMeasure (page 471) 
itemVariants (page 339) 
dimensionSetLines (page 427) 


History 


Version 
22.0 


Changes 
Fields Added: description2 


18.1 


Added Location. 


18.0 


Added. 
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Chapter 49: Purchase Receipts 


Unlike other Purchase Document endpoints, the Purchase Receipts endpoint points 
exclusively to the Posted Purchase Receipts in Business Central, as there is not an unposted 
form. 


This also means it does not rely on any aggregate mechanisms. 


Note: With this endpoint, a large amount of data is available, so it 
is key to consider using smart $£ilter and $select options. 
See Part 8: Chapter 89: Performance (page 511) and Part 1: 
Chapter 2: Reading / GET (page 17) for more information. 


Primary Key 


No. The identifier of the Purchase Receipt. The field is 20 characters and 
alphanumeric. 


Field Map 


API JsoN: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseReceipts/Sentity", 
"Qodata.etag": "W/\"JzIwOzEyNzE3NDEyNjJA3NzIyOTc3MzM3MTswMDsn\"", 
"id": "84c7a465-df3a-edl11l-bbae-6045bd8e554a", 


immto eno O TONO 

JstimarewtersiDeuc p 207 1E—() E19) EU 
JisyoxsnEduKelDkeuris 9 Weg oi 
MeepaiteN ea One Qn" 
"vendorNumber": "20000", 
"vendorName": "First Up Consultants", 
"payToName": "First Up Consultants", 
payl oContacen: “Ryan Melntesh, 
"payToVendorNumber": "20000", 
WshuploNamet = wu 

Wigioaietoeeiminereis te UM 
"buyFromAddressLinel": "100 Day Drive", 
"buyFromAddressLine2": "", 
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Vip uy Erom@altay Set Chukeagons, 

iouis cm Gomes vat NX Siu, 

VOUVE FOMaeatcenU MATT 

UowwEBombposiG ode! la Olle SIGN 

"shipToAddressLinel": "7122 South Ashford Street", 
"shipToAddressLine2": "Westminster", 

VelsaoexestiEy; Ug "Unde ilereieeyY 

Uislnayemociomimeey sg Moissy, 

"shipToState": ae 

'ishuspmTobosistoden aT 

"payToAddressLinel": "100 Day Drive", 
"payToAddressLine2": "", 

Jisyenva oC abies Bg. Oleo 

“pav LOC oun ya NERO ST 

"payToState" : TENN 

"payToPostCode": "61236", 

"currencyCode": "USD", 

"orderNumber": "", 

VilaseModuEired Date limes A029 SAS Ole 5l 8 (0) (81 85) TZA 


BUSINESS CENTRAL ENTITY: 
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Posted Purchase Receipt e «m oi oc a“ 
107208 - Graphic Design Institute 
Home Receipt More options © 
General Siow aie 
No. 107208 No. Printed 0 
Buy-from Vendor No Posting Date postingDate 
Buy-from Requested Receipt Date 
Name Promised Receipt Date 
Address lbuyFromAddressLinel Quote No. 
Address 2 buyFromAddressLine2 Order No. 
City buyFromCity Vendor Order No. 
State buyFromState Vendor Shipment No 
ZIP Code buyFromPostCode Order Address Code 
Country/Region buyFromCountry Purchaser Code 
Contact Bryce Jasso Responsibility Center 
Lines Manage Functions Line Fewer options 2 E 
Item 
Reference Unit o 
Type No No Description Location Code Quantity Meas 
-> item : 1906-S ATHENS Mobile Pedestal 10 PCS 
4 LI 
Invoicing Show mom 
Vendor No. payToVendorNumber Pay-to 
Contact no. CTOO0015 Name 
Address payToAddressLinel 
Address 2 payToAddressLine2 
State 
ZIP Code payToPostCode 


Country/Region 
Contact 
Department Code 


Customergroup Code 


payToCountr 


Bryce Jasso 
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Shipping 


Ship-to Location Code 

Name nbound Whse. Handling 

Addres Shipment Method Code 

Address 2 Lead Time Calculation 

Cty Expected Receipt Date 1/1/2021 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseReceipts 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /purchaseReceipts (84c7a465-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (1 entity shown from a longer list): 


1 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/purchaseReceipts", 

"value": [ 


{ 


"W/N"JzIwOz 


E3ND 


"Qodata.etag": EyNz EyNjA3NzIyOTc3MzM3MTswMDsnN"", 


"id": "84c7a465-df3a-edl1l-bbae-6045bd8e554a", 
Couma e ra Qno 

Visser AOOO 

Lisvomieadinc Deca 3g W202 il (I9) T7 
Welinepenee S 2912 Oil Oak 
"vendorNumber": "20000", 
"vendorName": "First Up Consultants", 
"payToName": "First Up Consultants", 
"payloGonuactitv e hyaneMcetnt: os 
"payToVendorNumber": "20000", 
"shipToName": "", 

Soio locontac ta WW. 


"buyFromAddressLinel": 
"buyFromAddressLine2": 


Wisi Eom dst 


"buyFromCountry": 
"buyFromState": 
"buyFromPostCode": 


"shipToAddressl 
"shipToAddressl 


MUR 
EMCO, 
“sS n 
Mea 

Wel SS 


Linel": 
Line2": 


MUOON Day: DEIER, 


"i22 South Ashford Street, 
"Westminster", 
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Hsiao caticw Ug We llenaeei 
uship ho e outs yas NUM 


WeimsheuerSEedE e m. UW 

ToHhiproPos tede Wish e720. 
"payToAddressLinel": "100 Day Drive", 
"payToAddressLine2": "", 


nse Ao C ate Ss Wielaisiere e e 
VierstwbreXeroxutoncaevo M ge MAIS E 


"payToState" : UAE 
DAV LOL OSE COG Cus M 5T PE 
Wieibligia saeco 2: WUD 
"orderNumber": "", 
wiaceModitiedDatelimen g 10710972 —(9)6) 52:52:08 9l 8 Om oman 
), 
CRUD Steps 


CREATING 


Creating a Posted Purchase Receipt requires a variety of operational steps that are beyond 
the scope of this book, as there may be a wide array of shipment requirements. In the most 
basic configurations, it involves Posting a Purchase Order with the Receive choice. 


Bound Actions 


No bound actions. 


e vendors (page 291) 

e countryRegion (page 402) 

e purchaseReceiptLines (page 288) 
e dimensionSetLines (page 427) 


| Version Changes 


18.2 Added order number. 
17.3 Added. 
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Chapter 50: Purchase Receipt Lines 


Unlike other Purchase Document Line endpoints, the Purchase Receipt Lines endpoint 
points exclusively to the Posted Purchase Receipt Lines in Business Central, as there is not an 
unposted form. 


This also means it does not rely on any aggregate mechanisms. 


Primary Key 


Document Id The generated identifier for the Purchase Receipt Line is created and 
used under the hood by Business Central to perfectly separate and 
identify. The field is a GUID. It is locked and managed by BC. 

Line No. The numeric identifier for the specific Purchase Receipt Line. It is unique 
only in the given Purchase Receipt. Integer Identifier. 


Field Map 


API JSON: 


1 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /purchaseReceipts (9aa6a271- 
df3a-edll-bbae-6045bd8e554a)/purchaseReceiptLines/S$entity", 

"Qodata.etag": "W/\"JzE50zg3NDULNDA4ODcyNjAOMDIwMTUxOzAwOyc=\"", 

"id": "a8a6a271-df3a-edl1-bbae-6045bd8e554a", 

"documentId": "9aa6a271-df3a-ed11-bbae-6045bd8e554a", 

"sequence": 10000, 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 
tesceriptron pg iere) ejes Charr, Blacki, 
"unitOfMeasureCode": "PCS", 


Hne oses Ib) Sir 

teamene ya ILO), 

"discountPercent": 0, 

"taxPercent": 6, 
"expectedReceiptDate": "2021-01-01" 


BUSINESS CENTRAL ENTITY: 


PART 4: PURCHASING 
CHAPTER 50: PURCHASE RECEIPT LINES 


e Vooe Order Address Code 


Country/Region Purchaser Code 


Contact Responsibility Cents 


Planned Expected 
Receipt Date Receipt Date 


ATHENS Mobile Pedestal a 10 1/1/2021 1/1/2021 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]])/purchaseReceipts (9aa6a271-df3a-ed1l1-bbae- 
6045bd8e554a) /purchaseReceiptLines 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]]))/purchaseReceipts (9aa6a271-df3a-ed11-bbae- 
6045bd8e554a) /purchaseReceiptLines(a8a6a271-df3a-ed11-bbae-6045bd8e554a) 


Example GET Request URI Single (Line Only): 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/purchaseReceiptLines (a8a6a271-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 


{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}}) /purchaseReceipts (9aa6a271- 
df3a-ed11-bbae-6045bd8e554a) /purchaseReceiptLines", 

"value": [ 

{ 
"Qodata.etag": "W/\"JzE50zg3NDULNDA4ODcyNjAOMDIwMTUxOzAwOyc=\"", 
"id": "a8a6a271-df3a-ed1l1-bbae-6045bd8e554a", 
"documentId": "9aa6a271-df3a-edl1-bbae-6045bd8e554a", 
"sequence": 10000, 


"lineType": "Item", 

"lineObjectNumber": "1900-S", 
"description": "PARIS Guest Chair, black", 
"unitOfMeasureCode": "PCS", 


vuni ecos: 09 

teanen Ye ILO), 

"discountPercent": 0, 

"taxPercent": 6, 
"expectedReceiptDate": "2021-01-01" 


"Qodata.etag": "W/\"JzZE50zY1INzYyMTMzODg3MTg4Nzg0MjcxOzAwOyc=\"", 
"id": "b3a6a271-df3a-edll-bbae-6045bd8e554a", 
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"documentId": "9aa6a271-df3a-ed1l1-bbae-6045bd8e554a", 
"sequence": 20000, 


"lineType": "Item", 

"lineObjectNumber": "1980-S", 
"description": "MOSCOW Swivel Chair, red", 
"unitOfMeasureCode": "PCS", 


iipimanieeroysie ^ p. EAS dir 

Weieren ene Sp 

"discountPercent": 0, 

"taxPercent": 6, 
"expectedReceiptDate": "2021-01-01" 


CRUD Steps 


CREATING 


Creating a Posted Purchase Receipt requires a variety of operational steps that are beyond 
the scope of this book, as there may be a wide array of shipment requirements. In the most 
basic configurations, it involves Posting a Purchase Order with the Receive choice. 


Bound Actions 


No bound actions. 


e purchaseReceipts (page 283) 
e accounts (page 38) 
e dimensionSetLines (page 427) 


History 


Version Changes 


22.0 Fields Added: description2 


17.3 Added. 
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Chapter 51: Vendors 


The Vendors endpoints allows access to the Vendors information in Business Central. 


Primary Key 


No. The identifier of the Vendor. The field is 20 characters and 
alphanumeric. 


Field Map 


API JSON: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/vendors/Sentity", 
"Qodata.etag": "W/\"JzE50zczMDMwOTE5NTc2NDAyNTQOOTMxOzAwOyc=\"", 


"id": "7115971e-df3a-edll-bbae-6045bd8e554a", 
number og. aL OOOO. 

"displayName": "Fabrikam, Inc.", 
"addressLinel": "10 North Lake Avenue", 
"addressLine2": "", 

Jose e Waves 

Istae GNI 

Verexubeuese ee: WOES 

D oostaii Gode TO 

"phoneNumber": "4255550101", 

"email": "krystal.york@contoso.com", 
"website": "www.royalmail.co.uk", 
"taxRegistrationNumber": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
Ucumnreneveodev M USIDM 

USLiesHl Siecle gs WY, 


"paymentTermsId": "8114971le-df3a-edl11l-bbae-6045bd8e554a", 
"paymentMethodId": "00000000-0000-0000-0000-000000000000", 
"taxLiable": true, 


Wewloeicyel 3 Ub sOOZ0_ ws 
WpalanGel NM 
"lastModifiedDateTime": "2022-09-23T01:29:42.272" 
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BUSINESS CENTRAL ENTITY: 


Vendor Card 


10000 - Fabrikam, Inc. 


Home Request Approval New Document Vendor Prices & Discounts Report More options 


General 


No. number cee Balance Due ($) 
Name displayName Document Sending Profile 
Blocked blocked Search Name 


Privacy Blocked IC Partner Code 


Al 


Last Date Modified astModifiedDateTime Purchaser Code 


[m 


Balance ($) balance Responsibility Center 


o 
8 


Balance ($) As Customer Disable Search by Name 


Address & Contact 


Address Mobile Phone No. 


“ee addresstinel ema 


Ade 2 i 
Address 2 addressLine2 Fax No 


e » - 
Country/Region Code countr Home Page website 


City 


n 
ct 


| | | i 


i Our Account No 


State state Language Code 


ZIP Code postalCode Contact 
Show on Map Primary Contact Code 


Phone No. phoneNumber Contact 


Invoicing 


Tax Registration No taxRegistrationNumber nvoice Disc. Code 


GUN Posting Details 


Tax Liable Gen. Bus. Posting Group 


Tax Area Code Vendor Posting Group 
Vendor No. Foreign Trade 


Currency Code currencyCode 
Bank Communication 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/vendors 
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Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/vendors(7115971e-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 


{ 


"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/vendors", 
"value": [ 


{ 
"Qodata.etag": "W/N"JzE5OzczMDMwOTESNTC2NDAyNTQOOTMxOzAwOyc-N"", 


"id": "7115971e-df3a-edl1-bbae-6045bd8e554a", 
number: M0000", 

"da spilayNamet: Ukabri ample 
"addressLinel": "10 North Lake Avenue", 
"addressLine2": "", 

WrestipwM Wcle 

Istic MA 

eoume yae MES - 

Utssieculicicle ve WS T EE 

"phoneNumber": "4255550101", 

"email": "krystal.york@contoso.com", 
"website": "www.royalmail.co.uk", 
"taxRegistrationNumber": "", 

"currencyId": "00000000-0000-0000-0000-000000000000", 
Vewmnencyicode ls SDN 

J'nseredb(o)eyerciexeke Ug WUE 


"paymentTermsId": "8114971e-df3a-edl11-bbae-6045bd8e554a", 
"paymentMethodId": "00000000-0000-0000-0000-000000000000", 
"taxLiable": true, 

Wolockedis. Lue 0 

Wioeuleince's (20) q/il . iS}, 

"lastModifiedDateTime": "2022-09-23T01:29:42.272" 


"Qodata.etag": "W/\"JzE40zM3MDI 1MTgyNDYONTM40DE50TE7MDA7Jw==\"", 
"id": "721597le-df3a-ed11-bbae-6045bd8e554a", 
"number": "20000", 


"displayName": "First Up Consultants", 
"addressLinel": "100 Day Drive", 
"addressLine2": "", 

Weste s Ulmer 

"statens ga 

countrya Ue 

I ocsisaiicodom 6 

"phoneNumber": "", 

"email": "evan.mcintosh@contoso.com", 
Inest susce no 
"taxRegistrationNumber": "", 
"currencyId": "00000000-0000-0000-0000-000000000000", 
"currencyCode": "USD", 

“irs 099 eecdaot a me 


"paymentTermsId": "8114971e-df3a-edll-bbae-6045bd8e554a", 
"paymentMethodId": "00000000-0000-0000-0000-000000000000", 
"taxLiable": true, 
"JsdiexelisexelUg- OO 20 Ur 
"balance": 4903.88, 
WilastModi tiedDatelame uomo 

), 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]])/vendors 


Example POST Request Body: 


"displayName": "New Company Name", 
"addressLinel": "Moonlander 1969" 


Example POST Response: 


1 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/vendors/Sentity", 
"Qodata.etag": "W/N"JzE5Ozg2NDOyMzA3OTE2OTk4Mj k3MTcxOzAwOyc=\"", 
Wielwe Walia 77 Qo AO S=eiclil Ib (Se: o (5010) OelsersreleG oil M 
"number": “VO0010", 


"displayName": "New Company Name", 
"addressLinel": "Moonlander 1969", 
"addressLine2": "", 

Wiese s MV 

Tatate: Uu 

J Grenubouese y 8 mu 

"posae odo NU 

"phoneNumber"; "", 

memari: u 

Misses estate ng m 
"taxRegistrationNumber": "", 
"currencyId": "00000000-0000-0000-0000-000000000000", 
UcunmenmneweoccM USD 
ieS iLO Cele a WW 


"paymentTermsId": "8214971e-df3a-ed1l1-bbae-6045bd8e554a", 
"paymentMethodId": "ee562523-df3a-edll-bbae-6045bd8e554a", 
"taxLiable": true, 


wWisubexsdissyoh ug VW xO 20) 
"bavanceWw 0; 
MhaseMocu raed Dat limes) O22 lO ZG MMR S 9 TE2 | S) T AS UD 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/vendors (a011779b-4055-ed11-8c36-000d3a8dc661) 


Example PATCH Request Body: 


"displayName": "Spare Brained Ideas AB", 
"number": "60000", 
"email": "noreply@sparebrained.com", 
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"website": "sparebrained.com" 


Example PATCH Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({ {companyID}})/vendors/Sentity", 
"@odata.etag": "W/\"JzE50zY5NzU4Nj gwOTI5Njk4MTAwODOxOzAwOyc=\"", 
Norge SO» seil sicko 00 0dsasdeo oi, 
"number": "60000", 


"displayName": "Spare Brained Ideas AB", 
"addressLinel": "Moonlander 1969", 
"addressLine2": "", 

Mese US UM. 

"state": ar 

ie Quinitetay aes uu 

WiexexehersidieTexeleg MIU 

"phoneNumber"; "", 

"email": "noreply@sparebrained.com", 
"website": "sparebrained.com", 
"taxRegistrationNumber": "", 
"currencyId": "00000000-0000-0000-0000-000000000000", 
Neurnencycode USDE, 

mrs (e eictoxelsu g WU 


"paymentTermsId": "8214971e-df3a-edll1-bbae-6045bd8e554a", 
"paymentMethodId": "ee562523-df3a-edll-bbae-6045bd8e554a", 
"taxLiable": true, 


vo lockeotia Wy xOO2O VY, 
"bpavancew 0; 
"lastModifiedDateTime": "2022-10-26T15:13:10.582" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /vendors (a011779b-4055-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


In the Vendors list, click on the New button in the Action Bar: 
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Vendors: All v | 2 Search -+ New lil] Delete Process v New Document v Vendor v 


Name Location Code Phone No. Contact 
Fabrikam, Inc. 4255550101 Krystal York 
First Up Consultants Evan McIntosh 
Graphic Design Institute Bryce Jasso 
Wide World Importers Toby Rhode 


Nod Publishers Raymond Hillard 


This will open a blank Vendor Card (depending on the system settings, you may have to 
select a Vendor Template). Click on the Name field (which should automatically assign a 
Vendor No. — if not, enter a Vendor No. manually) and enter text: 


Vendor Card (7) 


V00020 - Test Vendor 


Home Request Approval New Document Vendor Prices & Discounts Repor 


E Contact #3 Merge With... £'1 Apply Template E] Send Email 25 Pay Venc 


General 


V00020 es Balance ($) 


Test Vendor Balance ($) As Custo... 


Balance Due ($) 


UPDATING 


Open a Customer Card from the Vendor list and adjust the Name field. 


DELETING 


Select the Manage button in the Action Bar from the Vendors list and choose the Delete 
action. 


Bound Actions 


No bound actions. 
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The Vendor endpoint has many Navigation elements that allow you to fetch related 
endpoints with a built-in linkage to the Vendor context. This means that if you ask for the 
agedAccountsPayable endpoint to be expanded, you will get the content of the Aged 
Accounts Payable endpoint specific as a subitem for the Vendor entity. 


e countryRegion (page 402) 

e currencies (page 407) 

e paymentTerms (page 445) 

e paymentMethods (page 440) 

e picture (page 453) 

e defaultDimensions (page 417) 

e agedAccountsPayables (page 228) 
e contactsInformation (page 105) 


Changes 


Additional localization handling was put in place for taxRegistrationNo 
The contactsInformation navigation was added. 
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Chapter 52: Vendor Payments 


The Vendor Payments endpoint is a specialized version of the Journal Lines endpoint, so 
it is a layer on top of the General Journal Line, which reflects the way the Payments Journal 
sits on top of the General Journal Line as well. 


It makes each entry automatically has a few settings: 


e Document Type: Payment 
e Account Type: Vendor 
e Applies-To Doc. Type: Invoice 


If existing journal lines do not meet the above criteria, they will not be returned as part 
of the results. 


Since this is a Journal Line, it is still tied to Journal Batches — just like the Journal and 
Journal Lines setup. This means accessing the Vendor Payments via the Vendor Payment 
Journals endpoint or applying a journalId filter. 


Primary Key 


Journal Template Name The name of the Journal Template. The field is 10 
characters and alphanumeric. 

Journal Batch Name The name of the Journal Batch. The field is 10 characters 
and alphanumeric. 

Line No. It is a system-assigned integer. Typically, it is created in 
increments of 10000 so lines may be inserted between 
other records. 


Field Map 


API JsoN: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 

/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/vendorPayments/Sentity", 
"@odata.etag": "W/N"JzESOzMxMTI2NjAOODA1NzOANjMxNTOxOzAwOyc-N"", 
"jd": "4308b81b-Tlf9f-edl1—-9a88—000803a375c€05", 
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"journallId": "335a2523-df3a-edll-bbae-6045bd8e554a", 
"journalDisplayName": "GENERAL", 

"lineNumber": 10000, 

"vendorId": "7115971e-df3a-ed11-bbae-6045bd8e554a", 
"vendorNumber": "10000", 

Meroe auae S. WAOZ 204i 

"documentNumber": "G04001", 

"externalDocumentNumber": "", 

Weinvommmels 20) Til dE SI 

"appliesToInvoiceId": "33ed162f-df3a-edl1-bbae-6045bd8e554a", 


"appliesToInvoiceNumber": "108201", 

iekSpiexeijoemoin sg ARa boni kam Joss 4", 

PU GOTT n 8 "W Us 

M'beistglMtoxelabie bee bre Ece UMS 8 VAOZS Oi — 2 (GE TL sg SW 85) 2) 5 7S) gd 


BUSINESS CENTRAL ENTITY: 


Payment Journals 


Batch Name GENERAL journalDisplayName 


Manage Prepare Check 


Ef Po 


Document Document Document Account Acco. Bal. Account Bal. Account Applies-to Applies-to 
Posting Date Date Type No. Type No. Description Amount Type No. Doc. Type Doc. No 


4/11/2022 = 4/11/2022 Payment G04001 Vendor 10000  Fabrikam, Inc. 2,071.13 Bank Acco... CHECKING Invoice 108201 


The externalDocumentNumber and comment fields are also available. 


Note that the Payment Method and Balance Account fields are not available to the API. 


Example GET Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /vendorPaymentJournals (335a2523-df3a-edll-bbae- 
6045bd8e554a) /vendorPayments 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /vendorPaymentJournals (335a2523-df3a-edll-bbae- 
6045bd8e554a) /vendorPayments (43c8b81b-1f£9f-ed11-9a88-000d3a375c0b) 


Example POST Response: 
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"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /vendorPaymentJournals (335a25 
23-df3a-ed11-bbae-6045bd8e554a) /vendorPayments/Sentity", 

"@odata.etag": "W/N"JzE5OzMxMTI2NjAOODA1NzO4NjMxNTQxOzAwOyc-N"", 

Wichs waseso iioler -eeii lage -O00dsasT5e 0b, 

"journallId": "335a2523-df3a-edll-bbae-6045bd8e554a", 

"journalDisplayName": "GENERAL", 


"lineNumber": 10000, 


"yendorId": "7115971e-df3a-ed11-bbae-6045bd8e554a", 


"vendorNumber": "10000", 

VpOsit Lng Datseh p 20272 (ac TE Men 

"documentNumber": "G04001", 

"externalDocumentNumber": "", 

MieimtoxauE s 20:7 ESI 

"appliesToInvoiceId": "33ed162f-df3a-edll-bbae-6045bd8e554a", 
"appliesToInvoiceNumber": "108201", 

Iles eom atu ab damp eene 

IU Tm enm g "W Us 
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POST 


Example POST 


Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /vendorPaymentJournals (335a2523-df3a-edll-bbae- 
6045bd8e554a) /vendorPayments (43c8b81b-1f£9f-ed11-9a88-000d3a375c0b) 


Example POST 


Request Body: 


"description": "New line from API" 


Example POST 


Response: 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /vendorPaymentJournals (335a25 
23-df3a-edll-bbae-6045bd8e554a)/vendorPayments/S$entity", 

"Qodata.etag": "W/\"JzE50zgwNTc3NzIONDY1LOTgG4MDc2NzUxOzAwOyc=\"", 

"id": "bd67f£84b-2c9f-ed11-9a8a-6045bd02a733", 

"journalId": "335a2523-df3a-edll-bbae-6045bd8e554a", 

"journalDisplayName": "GENERAL", 

"lineNumber": 20000, 

"vendorId": "00000000-0000-0000-0000-000000000000", 


"vendorNumber":; "", 

WisOmedmeDence 3 WAOZ 20a 

"documentNumber": "G04002", 

"externalDocumentNumber": "", 

Wamounmiewss 07 

"appliesToInvoiceId": "00000000-0000-0000-0000-000000000000", 
"appliesToInvoiceNumber": "", 

Vdesermipelon ae Checking accoun, 

commenti Wi 


WlastModiiredDatelime'™: U2023-01-—Z2eTl6 35333352634" 


Note that 


the Description we submitted is overwritten. 
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PATCH 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /vendorPaymentJournals (335a2523-df3a-edll-bbae- 
6045bd8e554a) /vendorPayments (43c8b81b-1f£9f-ed11-9a88-000d3a375c0b) 


Example POST Request Body: 


"description": "Update from API" 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /vendorPaymentJournals (335a25 
23-df3a-ed11-bbae-6045bd8e554a) /vendorPayments/Sentity", 

"Qodata.etag": "W/N"JzE5OzMxMTI2NTk5NDQwMjOOMTAzNTgxOzAwOyc-N"", 

Watelle Wil serere dide ile ep edi yet etta Ore Lees Sel Oye" 

"journalId": "335a2523-df3a-edll-bbae-6045bd8e554a", 

"journalDisplayName": "GENERAL", 

"lineNumber": 10000, 

"vendorId": "7115971e-df3a-edll-bbae-6045bd8e554a", 

"vendorNumber": "10000", 

ISOS emacs i W022 OAs dus 

"documentNumber": "G04001", 

"externalDocumentNumber": "", 

Jieinquae pe Ogi legis, 

"appliesToInvoiceId": "33ed162f-df3a-edl1-bbae-6045bd8e554a", 


"appliesToInvoiceNumber": "108201", 

Wdescripeion : {Update From ARTS, 

"comment" : LLS n 

"lastModifiedDateTime": "2023-01-28T716:49:31.8672" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/journals (78ade£10-8750-ed11-946£-000d3a8dcb22) 


No request body is required. No response body will be given, only an HTTP Status of 204, “No 
Content.” 


CRUD Steps 


CREATING 
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Open the Payment Journals list and create a journal line. It needs to have the following 
fields set to be available to the API: 


e Document Type: Payment. 
e Account Type: Vendor. 
e Applies-To Doc. Type: Invoice. 


UPDATING 


Open the Payment Journals list and edit a field, such as the Amount field. 


DELETING 


You can delete a Payment Journal line. 


Bound Actions 


No bound actions. 


e customerPaymentJournals (page 126) 
e vendors (page 291) 

e dimensionSetLines (page 427) 

e applyVendorEntries (page 231) 

e vendorPaymentJournals (page 303) 


| Version Changes 
18.0 applyVendorEntries added. 
17.2 Added. 
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Chapter 53: Vendor Payment Journals 


This reflects the General Journal Batches of the first General Journal Template that is of 
Type: Payments. 


For more information about that, see the Journal (page 70) endpoint and the Part 8: 
Chapter 91: API Bugs (page 517). 


Primary Key 


Journal Template | The name of the Journal Template. The field is 10 characters and 
Name alphanumeric. 

Name The name of the Journal Batch. The field is 10 characters and 
alphanumeric. 


Field Map 


API JSON: 
{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({{companyID}}) /vendorPaymentJournals/Sentit 
y", 


"Qodata.etag": "W/N"JzIwOzEyNjY4OTE1MjMzMzkyNDgOMTczMTswMDsnN"", 
"id": "325a2523-df3a-edll-bbae-6045bd8e554a", 

COGN OAS Eye 

"displayName": "Cash receipts and payments", 
"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "10100", 

whastModpitedDarelime 702 2—0i9>7 TORIO a An Omri 


BUSINESS CENTRAL ENTITY: 
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PAYMENT Payments 


General Jour O Search -+New B Edit List 


Name f Description Bal. Account Type 3 No. Series 


CASH Cash receipts and payments G/L Account GJNL-PMT 
GENERAL : GENERAL G/L Account GJNL-PMT 
PAYPAL Paypal Transaction G/L Account 

PMT REG Bank Reconciliation Bank Account CHECKI.... GJNL-PMT 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /vendorPaymentJournals 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/vendorPaymentJournals (325a2523-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/$metadatafcompanies (((companyID])) /vendorPaymentJournals", 
"value": [ 


{ 


"Qodata.etag": "W/\"JzIwOzEyNjY40TEIMjJMzMzkyNDgOMTczMTswMDsn\"", 
"id": "325a2523-df3a-edll-bbae-6045bd8e554a", 


Mierexelesu OCASE 

"displayName": "Cash receipts and payments", 
"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "10100", 


nas eMocutaecdiatemimev 2022: 99 2/5m]0H95:2// 51 5 5]]) 2 


"Qodata.etag": "W/N"JzIwOzEyNjcwNzM2MzE2NDExODYwMTk3MTswMDsnN"", 
"id": "335a2523-df3a-edll-bbae-6045bd8e554a", 

codec CRNBEATM 

"displayName": "GENERAL", 

"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "10100", 

"lastModifiedDateTime": "2022-09-23T01:29:54.3572" 


"Qodata.etag": "W/N"JzIwOzEyNjMzNzcxOTIzMjgzMzM5Njk3MTswMDsn'N"", ) 
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"id": "345a2523-df3a-edll-bbae-6045bd8e554a", 

"codcm LPM RE GN 

"displayName": "Bank Reconciliation", 

"balancingAccountId": "00000000-0000-0000-0000-000000000000", 
"balancingAccountNumber": "CHECKING", 

"lastModifiedDateTime": "2022-09-23T01:29:54.372" 


} 
] 
} 
POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /vendorPaymentJournals 


Example POST Request Body: 


Yeodet PAW ATE, 
"displayName": "Paypal Payments" 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({ {companyID}}) /vendorPaymentJournals/Sentit 
y", 

"Qodata.etag": "W/\"JzIwOzE1MzgyODU2Njg4NTA2NjJAyMTI5MTswMDsn\"", 

CS VOWS Tere ILS) S—ecll l—Ses > —WOWcSiasreleoeul 4 

"code": "PAYPAL", 

"displayName": "Paypal Payments", 

"balancingAccountId": "00000000-0000-0000-0000-000000000000", 

"balancingAccountNumber": "", 

"lastModifiedDateTime": "2022-10-26T15:20:36.582" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/vendorPaymentJournals (76abd7f0-68d1-ec11-9617-cb648af3a4e2) 


Example PATCH Request Body: 


"displayName": "Paypal Transaction" 


Example PATCH Response: 
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{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({ {companyID}}) /vendorPaymentJournals/Sentit 
y", 

"@odata.etag": "W/N"JzIwOzEl1MzgyNDM3NzUONTAyM;jc2MDMAMTswMDsnV"" , 

Uganda S5 secs e 62:90/08/93!9 8/69/6191 

"code": "PAYPAL", 

"displayName": "Paypal Transaction", 

"balancingAccountId": "00000000-0000-0000-0000-000000000000", 

"balancingAccountNumber": "", 

"lastModifiedDateTime": "2022-10-26T15:21:07.742" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /vendorPaymentJournals (605651bd-4155-ed11-8c36-000d3a8dc661) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


As General Journal Batches are a subset of Journal Templates, the Journal Batches can 
be found on the General Journal Templates page under the Action Bar's Related -> Template 
-» Batches (with the appropriate Payment type template selected): 


General Journal Templates v Saved 


Pp Search -+ New E? Edit List li] Delete | Related ~ Automate v Fewer options 


E] Template > [md Batches 


Bal. Account Bal. Account 
Name f Description Type a Type No. No. Series 


— ASSETS : Fixed Asset G/L Journal Assets G/L Account FA-JNL 
CASHRCPT Cash receipts Cash Recei... G/L Account GJNL-RCPT 
GENERAL GENERAL General G/L Account GJNL-GEN 


This opens the editable list of General Journal Batches: 
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General Journal Batches Ø Search -+ New E? Edit List fü] Delete Home [if Post 


Bal. Account Bal. Account 
Name f Description Type No. No. Series 


— | DEFAULT : Default Journal Batch G/L Account FA-JNL 


Click New to create a new entry and manually enter an alphanumeric Name. 


UPDATING 


The safest and simplest method to trigger an Update of a General Journal Batches is to 
alter the Description field. 


DELETING 


General Journal Batches can be deleted. However, be aware that this will delete all 
related General Journal Lines that still need to be posted. 


Bound Actions 


No bound actions. 


Navigations 


e accounts (page 38) 
e vendorPayments (page 298) 


| Version Changes 


17.2 Added. 
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Chapter 54: Vendor Purchases 


This endpoint is to calculate the total of Purchases for a given Vendor within a period. 
There are two challenges with this endpoint: 


e Getting a single entry requires a strange Key, so filtering is better. 
e The value you retrieve is difficult to tally inside of Business Central. 


Additionally, you can filter on a date or range of dates to control the time period involved. 
The Single Entry Challenge: 


Most endpoints require a single Id (GUID) to get a single result. However, this endpoint 
requires: 


e The GUID Systemld of the Vendor. 
e The Vendor No. 
e The Vendor Name. 


If you omit any of these values, you will get: 


Nerror™ = 4 
"code": "BadRequest NotFound", 
"message": "The number of keys specified in the URI does not match number 


of key properties for the resource 'Microsoft.NAV.vendorPurchase'." 
} 
} 


If you try to leave any value blank, you will get: 


Merron”. x 
"code": "BadRequest ResourceNotFound", 
"message": "Resource not found for the segment 'vendorPurchases'.  Correl 


ationId:  0c5323ab-e18c-4b02-893c-f9ee0ea3c185." 
] 
} 


Additionally, this endpoint is not available as a Navigation from the Vendor endpoint, 
which would make it possible to access this information more easily. 


The Purchases Value: 
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The other challenge with documenting this endpoint is that it is a tally (sum) of the field 
Purchases (LCY) on the Vendor Ledger Entries. By default, this field cannot be shown on the 
Vendor Ledger Entries page. It is only visible by either the Page Inspector on the Vender Ledger 
Entries or by using the Statistics action on each and every purchase in the Vendor Ledger 
Entry. 


For getting this information, the next best option is to run the Vendor - Purchase List 
report, as shown below. 


Primary Key 


No. The identifier of the Vendor. The field is 20 characters and 
alphanumeric. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/vendorPurchases/Sentity", 

"vendorId": "7115971e-df3a-ed11-bbae-6045bd8e554a", 

"vendorNumber": "10000", 

Winnie a Winelonesticetiay, TINE, 

"totalPurchaseAmount": 21632.2, 

kda cemiiter alllecraoally'g e nul 


BUSINESS CENTRAL ENTITY: 
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Vendor - Purchase List 


Tax Registration No. Amount of Purchase (S) 


Fabrikam, Inc. 21,632.20 
Krystal York 

10 North Lake Avenue 

Atlanta, GA 31772 

USA 

First Up Consultants 

Evan Mcintosh 

100 Day Drive 

Chicago, IL 61236 

USA 

Graphic Design Institute 78,445.70 
Bryce Jasso 

33 Hitech Drive 


Baten: Fi waar 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID}}/APIBook/api/v2.0/ 
companies ({companyID}}) /vendorPurchases?$filter=vendorId eq 7115971e-df3a-ed1l1- 
bbae-6045bd8e554a 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/vendorPurchases(7115971e-df3a-edll-bbae-6045bd8e554a, '10000', 
'Fabrikam, Inc.') 


Example GET Request with a Date Filter for a single month: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/vendorPurchases(7115971e-df3a-edll-bbae-6045bd8e554a, '10000', 
'Fabrikam, Inc.')?$filter-(dateFilter FilterOnly ge 2022-01-01) and 

(Caterilrer PiltsrOniy te 2022-01-51) 


Example GET Response (2 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/vendorPurchases", 
"value": [ 


{ 
"vendorId": "7115971e-df3a-ed11-bbae-6045bd8e554a", 


"vendorNumber": "10000", 
"name Ubi utcam m bm 
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"totalPurchaseAmount": 21632.2, 
"eleneeimtdberese ial leciaOolly'g enuk 


"vendorId": "7215971e-df3a-edll-bbae-6045bd8e554a", 
"vendorNumber": "20000", 

mamenn MESE Up Consultants, 
"totalPurchaseAmount": 58609.8, 

dace militer al lhesiaOrally'g nul 


CREATING 


Creating and posting an Invoice for a Vendor will add data to this report resultset. 
Instructions on creating and pointing invoices is beyond the scope of this book. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


History 


No notable changes. 
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PART 5: INVENTORY 


In this Part, we will cover the various Inventory related endpoints in Business Central. 


Most of the endpoints in this section are information and setup related to enable getting 
more information based on values used in other entities in the API. 
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Chapter 55: Fixed Assets 


Primary Key 


No. 20 Character Alphnumeric field. 
Field Map 

API JSON: 

"value": [ 


{ 
"Qodata.etag": "W/\"JZIwOZExNDM5MDEONDg4NTc0ODAZMTY0MTswMDsn\"", 


"jd": "aaefl3bl-dali-efl1-9f85b-6045bde9cc61"', 

"number": "FA000010", 

"displayName": "Mercedes 300", 

"fixedAssetLocationCode": "ADM", 

"fixedAssetLocationId": "a5efl13bl-ddl11-ef11-9f8b-6045bde9cc61", 
"classCode": "TANGIBLE", 

Wop GikassCOcdels NEU 

"blocked": false, 

seria llNümDer nr ESO er 

"employeeNumber": "OF", 


"employeeId": "69ecli3bl-ddll-ef11-9f85b-6045bde9cc61", 
"underMaintenance": false, 
uleaestMoci E iriecDats times 29/94 —()5— ian 0 S aul il CAN 


"Qodata.etag": "W/\"JzIwOzExMzg4Nzg2NDU0OTI3MzM4MzMxMTswMDsn\"", 
"id": “adef13b1-dd1l-ef11-9f8b-6045bde9cc61", 
"number": "FA000020", 


"displayName": "Toyota Supra 3.0", 

"fixedAssetLocationCode": "SALES", 

"fixedAssetLocationId": "a6efl13bl-dd11-ef11-9f8b-6045bde9cc61", 
"classCode": "TANGIBLE", 

Iuswubcllasseocdeol UNE 

"blocked": false, 

usera iNumnmpe ra 3 Min LOL Sis) (OW 

"employeeNumber": "JO", 


"employeeId": "68ecl3bl-ddll-ef11-9f85b-6045bde9cc61", 
"underMaintenance": false, 
uTastMogi s reciData tines WOO QAO Sila 0 Sy a 2021 — (010) Wa 
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BUSINESS CENTRAL ENTITY: 


Fixed Asset Card | Work Date: 22/01/2026 


FA000010 - Mercedes 300 


Home Fixed Asset Report More options 


Acquire — EB Copy Fixed Asset... 


General 


No. FA000010 os Serial No. EA 12 394Q 


Description Mercedes 300 Search Description MERCEDES 300 


FA Class Code TANGIBLE v Responsible Employee OF 


FA Subclass Code CAR 


Depreciation Book Show more 


Depreciation Method Straight-Line Book Value 24,000.00 


Depreciation Starting Date 01/01/2025 Add More Depreciation Be; 


No. of Depreciation Years 


Depreciation Ending Date 31/12/2029 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID)])/fixedAssets 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies({{companyID}})/ fixedAssets (aaefl13bl-ddll-ef11-9f8b-6045bde9cc61) 


Example GET Response (single): 


{ 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/$metadatafcompanies (cf9f7 
b85-ddli1-ef11-9f8b-6045bde9cc61)/fixedAssets/$entity", 

"Qodata.etag": "W/N"JzIwOzExMzg4Nzg2NDUOOTI3MzMAMzMxMTswMDsnN"", 

"id": "adefl13b1-ddll-ef11-9f8b-6045bde9cc61", 

"number": "FA000020", 


"displayName": "Toyota Supra 3.0", 

"fixedAssetLocationCode": "SALES", 

"fixedAssetLocationId": "a6efl13bl-ddl1-ef11-9f8b-6045bde9cc61", 
"classCode": "TANGIBLE", 

msubelass€ode™; “CAR, 

"blocked": false, 

"serialNumber": "EA 12 395 Q", 

"employeeNumber": "JO", 


"employeeId": "68ecl3bl-ddll-ef11-9f85b-6045bde9cc61", 
"underMaintenance": false, 
WilastModPiredDacerime: “2024-05 Amilo s 5425 0/0/57: 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/fixedAssets 


Example POST Request Body: 


"displayName": "AlienWare Laptop" 


Example POST Response: 


{ 
"Qodata.context": "http://bcserver:7048/bc/api/v2.0/$metadatafcompanies (c£9£7 
b85-ddli1-efl11-9f8b-6045bde9cc61)/fixedAssets/$entity", 
"Qodata.etag": "W/N"JzIWOzE2MDIIODEI1MzU3ODMzNzUzNTgwMTswMDsnN"", 
Wigs “esdebeills-jb22—-en ll —8469-cebtabcaddl0i, 
"number": "FA000100", 
"displayName": "AlienWare Laptop", 
"fixedAssetLocationCode": "", 
"fixedAssetLocationId": "00000000-0000-0000-0000-000000000000", 
UelasisGode GE 
isupclilass oco. u 
"blocked": false, 
"serialNumber": "", 
"employeeNumber": "", 
"employeeId": "00000000-0000-0000-0000-000000000000", 
"underMaintenance": false, 
"lastModifiedDateTime": "2024-06-04T14:02:45.372" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/fixedAssets (e3debclb-7b22-ef11-8469-cc5fabca010£) 


Example PATCH Request Body: 


"fixedAssetLocationCode": "ADM", 
"serialNumber": "13513111563A" 


Example PATCH Response: 


{ 
"Qodata.context": "http://bcserver:7048/bc/api/v2.0/$metadatafcompanies (cf9f7 

b85-ddli1-efl11-9f8b-6045bde9cc61)/fixedAssets/$entity", 
"Qodata.etag": "W/N"JzE5OzIzMDcwNDEzMjUxMDA2MDE2MjExOzAwOyc-N"", 
!ngrgaesgdeleiss»? ef o469- cca ea: 
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"number": "FA000100", 

"displayName": "AlienWare Laptop", 
"fixedAssetLocationCode": "ADM", 
"fixedAssetLocationId": "a5efl13b1-ddll-ef11-9f8b-6045bde9cc61", 
icuassecocdoN nar 

insu clllasseocdouw Nt 

"blocked": false, 

"serialNumber": "13513111563A", 

"employeeNumber": "", 

"employeeId": "00000000-0000-0000-0000-000000000000", 
"underMaintenance": false, 

"lastModifiedDateTime": "2024-06-04T14:04:05.0472" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/fixedAssets (e3debclb-7b22-ef11-8469-cc5fabca010£) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


To create a new fixed asset, navigate to the Fixed Asset List and select the "New" button 
at the top of the page. 


P B Manage Home Fixed Asset Report More options 


Fi Calculate Depreciation... EB Copy Fixed Asset... 


No.t Description Responsible Employee FA Class Code FA Subclass Code FA Location Code Search Description Acquire 
FA000010 i Mercedes 300 OF TANGIBLE CAR ARM MERCEDES 300 

FA000020 Toyota Supra 3.0 TANGIBLE CAR SALES TOYOTA SUPRA 3.0 
FA000030 VW Transporter TANGIBLE CAR PROD VW TRANSPORTER 
FA000040 Conveyor, Main Asset TANGIBLE MACHINERY BUILD_2 CONVEYOR, MAIN... 
FA000050 Conveyor Belt TANGIBLE MACHINERY BUILD_2 CONVEYOR BELT 

FA000060 Conveyor Lift TANGIBLE MACHINERY BUILD_2 CONVEYOR LIFT 

FA000070 Conveyor Computer TANGIBLE MACHINERY BUILD_2 CONVEYOR COMP... 
FA000080 Lift for Furniture TANGIBLE MACHINERY PROD LIFT FOR FURNITU... 


FA000090 Switchboard TANGIBLE TELEPHONE RECEPTION SWITCHBOARD 


At least the description field will need to be filled in to generate a Fixed Asset No., which 
will insert the record. 
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General 


No. FA000110 oe ‘Component of Main Asset 


Description New Asset Search Description 


FA Class Code v Responsible Employee 


FA Subclass Code - Inactive. 


FA Location Code v Blocked 


Budgeted Asset Acquired 


Last Date Modified 


UPDATING 
Changing any field on the page, such as Search Description, will trigger an update to the 
database. 
DELETING 


Selecting Delete from the top of the Fixed Asset List, or the delete (trash) icon from the 
Fixed Asset Card will remove the record. Please note that if there are ledger entries associated 
with the Fixed Asset, this action will be prevented. 


Bound Actions 


No bound actions. 


Navigation 


e «Helpful suggestion with page no.» 


History 


| Version Changes 


23.00 Added. 
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Chapter 56: Fixed Asset Locations 


Primary Key 


Code Alphanumeric 10 character field. 


Field Map 


API JSON (2 ENTITIES FROM A LONGER LIST): 


"value": [ 
{ 
"Qodata.etag": "W/N"JzIwOzE3NzgzMjEyMjU4NjMzMzclNDYxMTswMDsnN"", 
"id": "ab5efl13bl-ddll-ef11-9f8b-6045bde9cc61", 


"code: ADM 
"displayName": "Administration", 
"lastModifiedDateTime": "2024-05-14T10:35:41.4832" 


"Qodata.etag": "W/N"JzIwOzE2MTcC2MjYzNDY2NzQ5NzM3MDQOMTswMDsnN"", 
"id": "alefl3bl-ddll-ef11-9f85b-6045bde9cc61", 


codec VB LUE, 
"displayName": "Blue Warehouse", 
"lastModifiedDateTime": "2024-05-14T10:35:41.482" 


BUSINESS CENTRAL ENTITY: 
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FA Locations: 4 o E -+ New [Ñ Delete Bẹ Edit List 


BLUE Blue Warehouse 

BUILD_2 Machinery Building 2 

GREEN Green Warehouse 

PROD Production 

RECEPTION Reception 

RED Red Warehouse 
Sales 


Yellow Warehouse 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({{companyID}}) /fixedAssetLocations 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({{companyID}}) /fixedAssetLocations (a5efl3bl-ddll-ef11-9f8b-6045bde9cc61) 


Example GET Response (single): 


{ 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/$metadatafcompanies (c£9£7 
b85-ddli1-ef11-9f8b-6045bde9cc61)/fixedAssetLocations/$entity", 

"Qodata.etag": "W/N"JzIwOzE3NzgzMjEyMjU4NjMzMzclNDYxMTswMDsnN"", 

Welle Weber il Seil olei ILE EIE etes GOA SloclacieeGil Mr 


"code": "ADM", 
"displayName": "Administration", 
"lastModifiedDateTime": "2024-05-14T10:35:41.4832" 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/fixedAssestLocations 


Example POST Request Body: 


coden: ff ces 
"displayName": "West Office" 


Example POST Response: 


{ 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/$metadatafcompanies (cf9f7 
b85-ddli1-ef11-9f8b-6045bde9cc61)/fixedAssetLocations/$entity", 

"Qodata.etag": "W/\"JzE50zE5MzMOMTkyOTgxNTM4MzY50DMxOzAwOyc=\"", 

WLS Weenies 2 ee lo 2 arb Lilo) Ce sitcloce dne Mr 


"Code": "OFFICE2", 
"displayName": "West Office", 
"lastModifiedDateTime": "2024-06-04T14:08:36.92Z" 


} 
PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/fixedAssestLocations (5af312ef-7b22-ef11-8469-cc5fabca010£f) 


Example PATCH Request Body: 


"displayName": "West Office - Park St." 


Example PATCH Response: 


{ 

"Qodata.context": "http://bcserver:7048/bc/api/v2.0/$metadatafcompanies (c£9£7 
b85-ddll-ef11-9f8b-6045bde9cc61)/fixedAssetLocations/S$entity", 

"Qodata.etag": "W/N"JzE5OzIOMjOOMjMINDYwNzgwNTCS5ODExOzAwOyc-N"", 

Wid Upri LAS tbe elu ooo ecl» OllOi 


"code": "OFFICE2", 
"displayName": "West Office - Park St.", 
"lastModifiedDateTime": "2024-06-04T14:10:24.4972" 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/fixedAssestLocations (5af312ef-7b22-ef11-8469-cc5fabca010£f) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


To insert a new Fixed Asset Location, use the "New" button at the top of the Fixed Asset 
List. Or select a new row at the bottom of the table. 


FA Locations | Work Date: 22/01/2026 


P B (Ere reais 


Code f Name 

ADM Administration 

BLUE Blue Warehouse 
BUILD 2 Machinery Building 2 
GREEN Green Warehouse 
OFFICE2 West Office - Park St. 
PROD Production 
RECEPTION Reception 

RED Red Warehouse 
SALES Sales 

YELLOW Yellow Warehouse 


UPDATING 


Triggering an update can be done by changing the Name Field. 


DELETING 


Select the row that you would like to delete and use the delete button at the top of the 
page. 
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Bound Actions 


No bound actions. 


Navigation 


e «Helpful suggestion with page no.» 


History 


| Version Changes 


23.00 Added. 
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Chapter 57: Items 


The Item is the core table of the Inventory system in Business Central and is used widely 
throughout the application. 


This endpoint exposes a small subset of key fields. 


One important cautionary note: In this endpoint, the inventory field is not just a read- 
only display of the existing stock levels. Updating this value (through a PATCH) will attempt to 
create an Item Journal and post it for that item. This will populate the following fields on the 
Item Journal: 


e Posting Date will always be today’s date. 

e Document No. will be the Item No. 

e Entry Type will be appropriate based on the adjustment. See the Quantity field 
below. 

e Item No. will be the Item No. 

e Description will be the Item's current Description. 

e Quantity will depend on the calculated difference between the current Inventory 
level and the submitted new value. If the existing inventory is 100, and you supply 
150, it will create a Positive Adjustment of 50. 


As you can see, this does not know anything about Locations or Bins, nor does it allow 
you to enter any costing information. It is advisable to approach this field with care and 
extensive testing if you plan to use it for data updates. 


Primary Key 


No. The identifier of the Item. The field is 20 characters and alphanumeric. 


Field Map 


API JSON: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/items/Sentity", 
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"@odata.etag": "W/\"JzE50zEyMDMzMjJAZNzY1MzM1MTEyNDgxOzAwOyc=\"", 
"id": "7615971e-df3a-edll-bbae-6045bd8e554a", 

Vm ei S96 

"displayName": "ATHENS Desk", 

"type": "Inventory", 

"itemCategoryId": "de582523-df3a-edl1-bbae-6045bd8e554a", 
"itemCategoryCode": "TABLE", 

"blocked": false, 

ien atia s "W UN 

"inventory": 4, 

Mune Pree: 0000587 

"priceIncludesTax": false, 

Uaec s Jp 

"taxGroupId": "56572523-df3a-edll-bbae-6045bd8e554a", 


"taxGroupCode": "FURNITURE", 

"baseUnitOfMeasureId": "e415971e-df3a-edll1-bbae-6045bd8e554a", 
"baseUnitOfMeasureCode": "PCS", 

"generalProductPostingGroupId": "d3562523-df3a-edll-bbae-6045bd8e554a", 
"generalProductPostingGroupCode": "RETAIL", 

"inventoryPostingGroupId": "d315971e-df3a-edll-bbae-6045bd8e554a", 
"inventoryPostingGroupCode": "RESALE", 

"IaseMocastueclbatevgmeu: W202 2-09-23 0d S220 9217/9]. 


BUSINESS CENTRAL ENTITY: 
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item Card e e t f] ci 

1900-S - PARIS Guest Chair, black 

Home Request Approval item Prices & Discounts More options 

Item Show less 

Description Item Category Code itemCategoryCode 

Blocked e Automatic Ext. Text 9 

Base Unit of Measure baseUnitOfMeasureCode Purchasing Code 

Last Date Modified lastModifiedDateTime Variant Mandatory if Exists Default (No) 

Inventory Show less 

Shelf No. Qty. on Asm. Component 0 

Created From Catalog item ə Stockout Waming Default (Yes) 

Search Description PARIS GUEST CHAIR, BLACK Prevent Negative Inventory Default (No) 

Quantity on Hand | Net Weight 83 

Qty. on Purch. Order 16 Gross Weight 9.55 

Qty. on Sales Order 4 Unit Volume 0.25 

Qty. on Job Order 0 Over-Receipt Code 

Qty. on Assembly Order 0 

Costs & Posting Show less 

Cost Details Posting Details - - 
ng eta generalProductionPosting 

Costing Method RFO Gen. Prod. Posting Group GroupCode 

Standard Cost 150.30 Tax Group Code 

Unit Cost 0.30 Inventory Posting Group inventoryPostingGroupCode 

Indirect Cost 96 0 Default Deferral Template 

Last Direct Cost 150.30 Foreign Trade 

Net Invoiced Qty. 0 Tariff No. 

Cost is Adjusted «D Country/Region of Origin C... 

Cost is Posted to G/L | € 

Purchase Prices & Discounts Create New... 


Prices & Sales 


Unit Price 

Unit Price Exd. Tax 
Price/Profit Calculation 
Profit 96 


Sales Prices & Discounts 


[—suiczzice — lus 


Profit=Price-Cost 


Create New... 


Allow Invoice Disc. 
Item Disc. Group 
Sales Unit of Measure 


Sales Blocked 


Show less 
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GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/items 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/items(7615971e-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 


/APIBook/api 
uvyalūet: 


{ 


6045bd8e554a 


6045bd8e554a 


/v2.0/Smetadata#companies ({{companyID}})/items", 
[ 


"Qodata.etag": "W/N"JzES5OzEyMDMzMjAzNzYlMzMIMTEyNDgxOzAwOyc-N"", 
"id": "7615971e-df3a-edll-bbae-6045bd8e554a", 

umb eu MOIS S. 

"displayName": "ATHENS Desk", 

WU toypeM “inventory, 

"itemCategoryId": "de582523-df3a-edll-bbae-6045bd8e554a", 
"itemCategoryCode": "TABLE", 

"blocked": false, 

Nerii es uu 

igiene wg: 4r 

rousse Ersrc eto OOE 

"priceIncludesTax": false, 

vunt ECosSE po WMO) a 

"taxGroupId": "56572523-df3a-edll-bbae-6045bd8e554a", 
"taxGroupCode": "FURNITURE", 

"baseUnitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"baseUnitOfMeasureCode": "PCS", 
"generalProductPostingGroupId": "d3562523-df3a-edl11-bbae- 


LU 


, 
"generalProductPostingGroupCode": "RETAIL", 
"inventoryPostingGroupId": "d315971e-df3a-edl1-bbae-6045bd8e554a", 
"inventoryPostingGroupCode": "RESALE", 
"LastModritasedbateTuime*: “2022-09-23 701 73222052774" 


"Qodata.etag": "W/\"JzIwOzE0MjcxNDUxOTA2NTgzNjU2Njc3MTswMDsn\"", 
"id": "7715971e-df3a-ed11-bbae-6045bd8e554a", 

JhsgepüdexescuAg. OOS 

"displayName": "PARIS Guest Chair, black", 

Iitivao eMe mte ory, 

"itemCategoryId": "d9582523-df3a-edll-bbae-6045bd8e554a", 
"itemCategoryCode": "CHAIR", 

"blocked": false, 

Wien abso e n 

"inventory": O0, 

Umen esn i Ceha iC) teh. 

"priceIncludesTax": false, 

vani ECosSt: TESI) ssl 

"taxGroupId": "56572523-df3a-edll-bbae-6045bd8e554a", 
"taxGroupCode": "FURNITURE", 

"baseUnitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"baseUnitOfMeasureCode": "PCS", 
"generalProductPostingGroupId": "d3562523-df3a-ed11-bbae- 


" 
, 
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"generalProductPostingGroupCode": "RETAIL", 
"inventoryPostingGroupId": "d315971e-df3a-edll-bbae-6045bd8e554a", 
"inventoryPostingGroupCode": "RESALE", 

"lastModifiedDateTime": "2022-09-23T01:32:20.2772" 


), 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/items 


Example POST Request Body: 


Wiaubhilexsse ^. MOTO LT 
"displayName": "Super Vaccuum Cleaner" 


Example POST Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/items/Sentity", 
"Qodata.etag": "W/N"JzESOZzkyNTUyOTUONj I3Mjgl1OTOzMTkxOzAwOyc-N"", 
"id": "1ece2509-e855-ed11-8c36-000d3a8dcc52", 
MUM Stee OQ 
"displayName": "Super Vaccuum Cleaner", 
i tsyop eo Time mts os yA 
"itemCategoryId": "00000000-0000-0000-0000-000000000000", 
"itemCategoryCode": "", 
"blocked": false, 
Lucret LLS Ud 
UELonceimecieyy Me. 0p 
Mn E PrTCE Tn 
"priceIncludesTax": false, 
vuni COS Mp 07 
"taxGroupId": "00000000-0000-0000-0000-000000000000", 


"taxGroupCode"; "", 
"baseUnitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"baseUnitOfMeasureCode": "PCS", 
"generalProductPostingGroupId": "d3562523-df3a-edll-bbae-6045bd8e554a", 
"generalProductPostingGroupCode": "RETAIL", 
"inventoryPostingGroupId": "d315971e-df3a-edll-bbae-6045bd8e554a", 
"inventoryPostingGroupCode": "RESALE", 
WilastModittedbateLime “2022102 7 p]. .] 5159140) 507/97, 

} 
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PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /items (lece2509-e855-ed11-8c36-000d3a8dcc52) 


Example PATCH Request Body: 


"displayName": "Regular Vaccuum Cleaner", 
Nie mule va 900i 


Example PATCH Response: 


{ 
"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/items/Sentity", 
"@odata.etag": "W/\"JzIwOzE1Mzc5NjJMxOTA30TMOMzg2MjQ1MTswMDsn\"", 
"id": "lece2509-e855-ed11-8c36-000d3a8dcc52", 
mise: aeo Od 
"displayName": "Super Vaccuum Cleaner", 
"type": "Inventory", 
"itemCategoryId": "00000000-0000-0000-0000-000000000000", 
"itemCategoryCode": "", 
"blocked": false, 
xerit M 
inventory. Oil, 
Noms Ernie 10). 
"priceIncludesTax": false, 
UME COS LO! 
"taxGroupId": "00000000-0000-0000-0000-000000000000", 


NeaxGroupCodem | nu, 

"baseUnitOfMeasureId": "e415971e-df3a-edll-bbae-6045bd8e554a", 
"baseUnitOfMeasureCode": "PCS", 

"generalProductPostingGroupId": "d3562523-df3a-edll-bbae-6045bd8e554a", 
"generalProductPostingGroupCode": "RETAIL", 

"inventoryPostingGroupId": "d315971e-df3a-edll-bbae-6045bd8e554a", 
"inventoryPostingGroupCode": "RESALE", 

""astModifiedbateTime'": "2022-—10-—2TT]9 :52:52527947)4" 


DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /items (1ece2509-e855-ed11-8c36-000d3a8dcc52) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content”. You may not be able to delete an Item if it has been used for transactions. 
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CRUD Steps 


CREATING 


In the Items list, click on the New button in the Action Bar: 


Items: All v | O Search -+ New lil] Delete Process v Item ^^ Prices & Discounts v Attributes ^^ 


Cost 
Substi... Assem... Base Unit of is 
Description Exist BOM Measure Adj... 


PARIS Guest Chair, black Inventory 
ATHENS Mobile Pedestal Inventory 
LONDON Swivel Chair, blue Inventory 
ANTWERP Conference Table Inventory 
Conference Bundle 1-6 Inventory 
AMSTERDAM Lamp Inventory 


Conference Bundle 1-8 Inventory 


This will open a blank Item Card (you may have the system configured to use Item 
Templates, which will ask you to select an Item Template). 


Click in the Description field (which should automatically assign an Item No. - if not, 
enter an Item No. manually) and enter text: 


1000 


Home Request Approval Item Prices & Discounts More options 


E Copy Item 4g Adjust Inventory #4 Create Stockkeeping Unit CT Apply Template 


Item Show more 


No. Ue Base Unit of Measure 


Description Item Category Code 


Blocked e» Variant Mandatory if ... Default (No) 


Type Inventory 


UPDATING 
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Open an Item Card from the Items list and adjust the Description field. 


DELETING 


Select the Manage button in the Action Bar from the Items list and choose the Delete 
action. Note that if there are transactions for the Item, you may not be able to delete the Item. 


Bound Actions 


No bound actions. 


e itemCategories (page 331) 

e unitsOfMeasure (page 471) 

e picture (page 453) 

e defaultDimensions (page 417) 

e itemVariants (page 339) 

e genProdPostGroups (page 350) 
e inventoryPostGroups (page 354) 


Changes 


displayName2 added. 

Gen. Product Posting Group and Inventory Posting Group fields and Navigations 
added. 

Additional validations on the Base Unit of Measure. 
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Chapter 58: Item Categories 


In Business Central, Items can have an Item Category, which is a heirarchical data structure 
for tagging items for easy and powerful filtering in combination with the Item Attributes 
system. 


Primary Key 


Code The unique identifier of the Item Category. The field is 20 characters 
and alphanumeric. 


Field Map 


API JsoN: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/itemCategories/Sentity", 

"@odata.etag": "W/\"JzIwOzEONTM30Dc2MTYZNjU5Nj k40DU4MTswMDsn\"", 

"id": "d9582523-df3a-ed1l1-bbae-6045bd8e554a", 

oode t a CHAIR, 

"displayName": "Office Chair", 

WilaseModtttredDakvelime"-— "2022-09-73 Ol 22/9 1: 5 29) 71M 


BUSINESS CENTRAL ENTITY: 
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tem Category Card 


CHAIR 


[li] Delete More options 


General 


Code Parent Category FURNITURE 
Description 


Attributes 


Attribute t Default Value Unit of Measure Inherited From 
FURNITURE 
FURNITURE 
FURNITURE 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID])])/itemCategories 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/itemCategories (d9582523-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (4 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/itemCategories", 
"value": [ 


{ 
"Qodata.etag": "W/\"JzIwOzEONTM30Dc2MTYZNjU5Njk4ODU4MTswMDsn\"", 


"id": "d9582523-df3a-edll-bbae-6045bd8e554a", 
"code “CHAIR, 

"displayName": "Office Chair", 
"lastModifiedDateTime": "2022-09-23T01:29:51.243Z2" 


"Qodata.etag": "W/N"JzIWOzEONTM3ODcCOMzIxMTCONDYxMjAOMTswMDsnN"", 
"id": "da582523-df3a-edll-bbae-6045bd8e554a", 
Werle EDESKT 

"displayName": "Office Desk", 
VilaseModttredDateiime =. “2022 oT POI SH 
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"Qodata.etag": "W/N"JzIwOzEONTM3ODgwMTc5MTAwOTA5NjUxMTswMDsnN"", 
"id": "db582523-df3a-edl1-bbae-6045bd8e554a", 

code M WPAN CANONS Ia 

"displayName": "Office Furniture", 

"lastModifiedDateTime": "2022-09-23T01:29:51.262" 


"Qodata.etag": "W/N"JzIwOzEONTM3ODcOMDMANzYONjU2NZzE2MTswMDsnN"", 
"id": "dc582523-df3a-ed11-bbae-6045bd8e554a", 


codo UMS e 
"displayName": "Miscellaneous", 
MikaceModiamiledDakelimen sue Oa NOTZ TOZ 511 27 gg 


}, 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/itemCategories 


Example POST Request Body: 


ogden: E C 
"displayName": "Electronics" 


Example POST Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/itemCategories/Sentity", 
"Qodata.etag": "W/\"JzIwOzEONTM20TI 3NTIxOTk2NDMONDY3MTswMDsn\"", 
"id": "600c2fe3-ef55-ed11-8c36-000d3a8dec52", 


"Code": NORNISE Gur 
"displayName": "Electronics", 
Ara slew cibaria e A022 NO 2a ule. OBTENUS ME 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/itemCategories (cca42f£20-f2d1-ec11-9617-cb648af3a4e2) 


Example PATCH Request Body: 


"displayName": "Really Powerful Electronics" 
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Example PATCH Response: 


{ 
"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/itemCategories/Sentity", 
"Qodata.etag": "W/\"JzIwOzEONTM20TI 3NzM2NzcyNTUWNJAIMTswMDsn\"", 


"id": "600c2fe3-ef55-ed11-8c36-000d3a8dcc52", 
Teoden NUES UT 
"displayName": "Really Powerful Electronics", 


“ias eModitt redDa cerime qt] 2-0 CUTEM GIO 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /itemCategories (600c2fe3-ef55-ed11-8c36-000d3a8dcc52) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


In the Item Categories list, click on the New button in the Action Bar: 


Item Categories 


4? Edit View  & Recalculate 


LD Search 


+New EEditList [i] Delete More options 


Description 


CM 
CM COMMER 
CM CONSUM 
FURNITURE 
CHAIR 
DESK 
TABLE 
MISC 
SUPPLIERS 


Coffee Makers 
Commercial Models 
Consumer Models 
Office Furniture 
Office Chair 

Office Desk 
Assorted Tables 
Miscellaneous 


Office Supplies 


This will open a blank Item Category Card. Assign a Code and enter a Description. 
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e + jj G Zl 
Item Category Card 


More options 


General 


Code 


Parent Category 


Description 


Attributes Manage 


Attribute f Default Value Unit of Measure 


E 


Inherited From 


UPDATING 


Open an Item Category Card from the Item Categories list and adjust the Description 
field. 


DELETING 


Select the Manage button in the Action Bar from the Item Categories list and choose the 
Delete action. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


History 


No notable changes. 
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Chapter 59: Item Ledger Entries 


In Business Central, when Items are moved around, into or out of stock, an Item Ledger 
Entry records all the pertinent information about the transaction. 


This endpoint exposes some fields of that ledger for analysis. 


Note: With this endpoint, a large amount of data is available, so it 
is key to consider using smart $£ilter and $select options. 
See Part 8: Chapter 89: Performance (page 511) and Part 1: 
Chapter 2: Reading / GET (page 17) for more information. 


Primary Key 


Entry No. A sequential integer assigned to the Item Ledger Entry during 
creation. 


Field Map 


API JsoN: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/itemLedgerEntries/Sentity", 
"Qodata.etag": "W/\"JzIwOzE1MzU3MzI5NzQOMTk4MTc3NDkwMTswMDsn\"", 
"id": "5c28755f-df3a-edll—-bbae-6045bd8e554a", 
"entryNumber": 330, 


"itemNumber": "1896-S", 

JisYoxsESueKelDEuE S S W929i S9). 
Nenerylype;| "Sade" 

"sourceNumber": "30000", 

"sourceType": "Customer", 
"documentNumber": "S-SHPT102170", 
"documentType": "Sales x0020 Shipment", 
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likekersiesealigeskoia! S WW 


gauan eye db, 

"salesAmountActual": 4003.2, 

"costctAmountActuadl*: 31225787 
wikasteModitaedDatelaime 09/9: 09 oT STET 


BUSINESS CENTRAL ENTITY: 


Item Ledger Entries O Search [QFindentries. Enty [i Order Tracking W Application Worksheet More options 


Document Department 
Code 


SALES 4,003.20 -3,122.80 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/itemLedgerEntries 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies((companyID)])/itemLedgerEntries (5c28755f-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/itemLedgetEntries", 
"value": [ 
{ 


"Qodata.etag": "W/N"JzE5Ozg1NTM5MDcCwNTUOODY2MDCONDkxOzAwOyc-N"", 
"id": "1226755f-df3a-edll1-bbae-6045bd8e554a", 
"entryNumber": 303, 


"itemNumber": "1896-S", 

MOS EME DEES '"7202.9—1:2-— 9109. 
"entryType": "Sale", 

"sourceNumber": "30000", 

"sourceType": "Customer", 
"documentNumber": "S-SHPT102155", 
"documentibypes: “Salles! 0020 (Shipment, 
Welssioienjisiemormyg WW 

WretiienaicaLiey S =y 

"salesAmountActual": 3002.4, 
"costAmountActual": -2342.1, 
MilasteModittredDakelime 2027-09 —2 si see An 


"Qodata.etag": "W/\"JzIwOzExMzQyNzI 4MjU1Nzk3MjU5ODUIMTswMDsn\"", 
"id": "9327755f-df3a-edl1l-bbae-6045bd8e554a", 
"entryNumber": 320, 


"itemNumber": "1896-S", 
Vposie ing Dasa m WIS AE (mM 
"entryType": "Sale", 
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"sourceNumber": "10000", 

"sourceType": "Customer", 

"documentNumber": "S-SHPT102165", 
"documentType": "Sales x0020 Shipment", 
UelaserenjoiesoinY g UU. 

Wieiiicroncahiey B cn 

"salesAmountActual": 6004.8, 

"costAmountActual": -4684.2, 
"lastModifiedDateTime": "2022-09-23T01:31:31.92" 


"Qodata.etag": "W/\"JzIwOzE1MzU3MzI5NzQOMTk4MTc3NDkwMTswMDsn\"", 
"id": "5c28755f-df3a-edll-bbae-6045bd8e554a", 
"entryNumber": 330, 


"itemNumber": "1896-S", 

"postingDate": "2022-01-30", 

Henery ype "Sade" 

"sourceNumber": "30000", 

"sourceType": "Customer", 

Wdocument Numbers; S SETTE 
"documentType": "Sales x0020 Shipment", 
clesie on M 

lig ieinibiney Ye zl, 

"salesAmountActual": 4003.2, 
"costAmouni Actual M 9122787 
Jbevsnglntexelabaeakcxeliblenereurabareg. YU 20 22-0’) 52 9u((0)40 8 sulle Sil c Sa 


), 


CRUD Steps 


Unfortunately, there can be many complexities to creating transactions involving Items, 
including many restrictions around how to even adjust items into stock. Consult your Business 
Central professional, but note that any transaction involving an item, such as receiving a 
Purchase Order, will create transactions in the Item Ledger Entry table. 


Bound Actions 


No bound actions. 


e items (page 323) 


History 


| Version Changes 
19.0 Added. 
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Chapter 60: Item Variants 


In Business Central, one of the ways you can manage Items is to use Item Variants when 
you have a group of items that are nearly identical but for some small variation. When using 
Item Variants, you will use both the Item Number and the Variant Code as a combined key. 


Variant Codes are a subsidiary setup to Items, so Item 1896-S can have an Item Variant 
code of RED, and item 1906-S can also have a code of RED. This will be two entries in the Item 
Variant table. 


In the API, the Item Variant system is primarily made available on Purchase and Sales 
document lines. 


Primary Key 


Item No. The Item No. to which this record belongs. The field is 20 characters 
and alphanumeric. 

Code The unique (per Item) Variant identifier. The field is 10 characters and 
alphanumeric. 


Field Map 


API JsoN: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/itemVariants/Sentity", 
"Qodata.etag": "W/N"JzE5OzQ2MzAxODYyMTAxMTESNzMxNjUxOzAwOyc-N"", 
"id": "7753d18a-df3a-ed1l1-bbae-6045bd8e554a", 
"itemId": "7553d18a-df3a-ed11-bbae-6045bd8e554a", 


"itemNumber": "SP-SCM1006", 
"code BLACK 
"description": "AutoDripLite - Black" 


BUSINESS CENTRAL ENTITY: 
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To access the Item Variants, there is an Action in the Related action bar area of the Item 
Card: 


Item Card 


SP-SCM1006 : AutoDripLite 


Home Request Approval Item Prices & Discounts Actions w [Related ^^ Reports w Automate v 


I 
EB Copy Item jj Adjust Inventory — /& Create Stockkeeping Unit t1 © History 


fb Variants 
Item 
ES Availability m] Identifiers 


PS SP-SCMT006 [ee Basa Una EPI Purchases & Item References 


Description AutoDripLite Item Categ: 


1E Sales E Units of Measure 


This will open the Item Variant list: 
SP-SCM1006 - AutoDripLite 


Item Variants OJ Ar +New  BZEditList »?/ More options 


Description 


AutoDripLite - Black 


AutoDripLite - Red 
AutoDripLite - White 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/itemVariants 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/itemVariants (7753d18a-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/itemVariants", 
"value": [ 


{ 


"Qodata.etag": "W/N"JzE5OzQ2MzAxODYyMTAxMTESNzMxNjUxOzAwOyc-N"", 
"id": "7753d18a-df3a-edll-bbae-6045bd8e554a", 
"itemId": "7553d18a-df3a-edll-bbae-6045bd8e554a", 
"itemNumber": "SP-SCM1006", 
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codec BIET 
Uclipierjenois A Wale pienjoumice, = Blacks 


"@odata.etag": "W/\"JzE50zQ2Mj k5MDAZNTIINJESNTEWNJYxOzAwOyc=\"", 
"id": "7853d18a-df3a-edll-bbae-6045bd8e554a", 

"itemId": "7553d18a-df3a-edl1l-bbae-6045bd8e554a", 

"itemNumber": "SP-SCM1006", 

"codes MWhl int, 

"description": "AutoDripLite - White" 


"Qodata.etag": "W/\"JzE50z02Mj k2MTQONDMSNDY5NTcOMDYxOzAwOyc=\"", 
"id": "7953d18a-df3a-edll-bbae-6045bd8e554a", 
"itemId": "7553d18a-df3a-ed11-bbae-6045bd8e554a", 


"itemNumber": "SP-SCM1006", 
Neode RED, 
Jelssyescaslgsiealens t: Winco enjollnkice Redy 


}, 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/itemVariants 


Example POST Request Body: 


"itemId": "7553d18a-df3a-edll-bbae-6045bd8e554a", 
codo ss BUR 
"description": "AutoDripLite - BLUE" 


Example POST Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/$metadatafcompanies(((companyID)])/itemVariants/Sentity", 
"@odata.etag": "W/N"JzESOzQ2MTEA4NDYzNTI3NjOyNjYOODIxOzAwOyc-V"", 
"id": "8bd6853e-0395-ed11-bff5-00224803bb96", 
"itemId": "7553d18a-df3a-edll-bbae-6045bd8e554a", 


"itemNumber": "SP-SCM1006", 
Jerexele sg WIESE 
"description": "AutoDripLite - BLUE" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies({companyID}})/itemVariants (8bd6853e-0395-ed11-bff5-00224803bb96) 
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Example PATCH Request Body: 


"description": "AutoDripLite - Navy Blue" 


Example PATCH Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({{companyID}})/itemVariants/Sentity", 
"@odata.etag": "W/\"JzE50zQ2MTE4NDY zNTIwOTAyNDcOMTgxOzAwOyc=\"", 
Ig O95 se SIS =e il pi 2229/09196 
"itemId": "7553d18a-df3a-ed11-bbae-6045bd8e554a", 


"itemNumber": "SP-SCM1006", 
Nico c NETS UB. 
"description": "AutoDripLite - Navy Blue" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/itemVariants (8bd6853e-0395-ed11-bff£5-00224803bb96) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


The Item Variants list in Business Central is directly editable. So, open the list and create 
a new line. 


SP-SCM1006 - AutoDripLite v/ Saved (= 


Item Variants | po Search -+ New Ez Edit List li] Delete More options 2 Y 


Description 


AutoDripLite - Black 
AutoDripLite - Red 
AutoDripLite - White 


UPDATING 
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The Item Variants list in Business Central is directly editable. So, open the list and change 
a line, such as the Description field. 


DELETING 


The Item Variants list in Business Central is directly editable. So, open the list and delete 
a line. 


Bound Actions 


No bound actions. 


Navigations 


e items (page 323) 


History 


No notable changes. 
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Chapter 61: Locations 


Locations are places, such as warehouses, where you buy, store, or sell items. Business 
Central uses locations to help keep track of inventory in both simple and complex warehouse 
processes. 


The endpoint exposes a small list of information fields. 


Primary Key 


Code The short identifier of the chosen Location. The field is 10 characters 
and alphanumeric. 


Field Map 


API JSON: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/locations/Sentity", 
"Qodata.etag": "W/\"JzE50zEONTg1NTM5NDAONTU3NjQzZMTcxOzAwOyc=\"", 
"id": "1715971e-df3a-ed11-bbae-6045bd8e554a", 
code ss WEA, 
"displayName": "East Warehouse", 
Ucontsac ts. et i Sm 
"addressLinel": "South East Street, 3", 
"addressLine2": "", 
Messa MU AIF a 
Wstavel "GAM, 
Scoumt rya MORSU 
upostcalCoden VS TA 
"phoneNumber":; "", 
Memar lne ae 
"website": wor 
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BUSINESS CENTRAL ENTITY: 


Location Card 


MAIN : Main Warehouse 


W Zones ææ Bins [Inventory Posting Setup  % Warehouse Employees — f Online Map  & Dimensions 


General 


Code Exclude from Tax Calc... 
Name Tax Area Code 


Use As In-Transit Tax Exemption No. 


Address & Contact 


Address Contact 
Address Contact 
Address 2 Phone No. 
City j Email 

State Home Page 


ZIP Code Electronic Document 


Country/Region Code ID Ubicacion 


Show on Map 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/locations 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /locations (171597le-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 
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"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/locations", 
"value": [ 


{ 


"@odata.etag": "W/\"JzE50zEONTg1NTM5NDAONTU3NjQzMTcxOzAwOyc=\"", 
"id": "1715971e-df3a-ed11-bbae-6045bd8e554a", 


vecde tn URAC ry 

"displayName": "East Warehouse", 
"contact gettesmutht 
"addressLinel": "South East Street, 3", 
"addressLine2": "", 

reste Wedam 

dee S "GA", 

scourn ryan We. 

Jheroxenerull(eiexel2d s. SHE EM. 
"phoneNumber":; "", 

Mamail”: uu 

Ines woe 


"@odata.etag": "W/\"JzIwOzEwODk2NjA3MjAwMDkyMDQ50DI3MTswMDsn\"", 
"id": "1815971e-df3a-ed11-bbae-6045bd8e554a", 


Ineocle "MAIN", 

"displayName": "Main Warehouse", 
I conmtact meam olemPolamnou 
"addressLinel": "520 N Michigan Ave", 
"addressLine2": "", 

Vesey 3 Uie y 

stations ABS 

Scounmt rya UOS. 

Cpostcal Codet VOTO db IET 
"phoneNumber":; "", 

memar is MNT 

Wel Suntec woe 


), 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID])])/locations 


Example POST Request Body: 


"code": "hello", 
"displayName": "API Created Location" 


Example POST Response: 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/locations/Sentity", 
"@odata.etag": "W/N"JzE5OzMxNTIxMDE4MjYA4NjYwMDkwOTUxOzAwOyc-N"", 
Waele USO een beu 9esio 909065896 c»2 

oode S Weim 7 

"displayName": "API Created Location", 
"eontact™: wm 

vaddressrineld m 
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"addressLine2": "", 
Weste LU 
Tatate": uw 
"rerenbbouese e m 

Epos wali€ode o uu, 
"phoneNumber": "", 
Memar ns Uu. 

Miserere IE rg nw 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /locations (507ce48f-£455-ed11-8c36-000d3a8dcc52) 


Example PATCH Request Body: 


Werle e USUS 

"displayName": "Spare Brained Ideas Headquarters", 
"contact": "CEO of Spare Brained Ideas", 
"addressLinel": "Somewhere In The World", 

WG alae Tas WIN TAYE 

"country": "Sweden", 

I oo stadio OE 

"phoneNumber":; "", 

"email": "noreply@sparebrained.com", 

"website": "sparebrained.com" 


Example PATCH Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/locations/Sentity", 
"Qodata.etag": "W/N"JzE5OzMxNTIxMDE4MjYA4NjYwMDkwOTUxOzAwOyc-N"", 
Mido oce edds e96z:00/08/93!5 dc 95217 


"codcu MU SPIEON 

"displayName": "Spare Brained Ideas Headquarters", 
"contact. “CEO of spare Brawned ideas, 
"addressLinel": "Somewhere In The World", 
"addressLine2": "", 

Moises als RON AA 

"state": VALE 

Veronese WIS e 

Vaostvalicode: OOO OO 

"phoneNumber": "", 

"email": "noreply@sparebrained.com", 
"website": "sparebrained.com" 


PART 5: INVENTORY 
CHAPTER 61: LOCATIONS 


DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /locations (507ce48f-f£455-ed11-8c36-000d3a8dcc52) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


In the Locations list, click on the New button in the Action Bar: 


Locations 


2 Search New Manage Home Report Functions More options 


+ New Transfer Order 


Code f Name 
EAST : East Warehouse 
MAIN Main Warehouse 


NORTH Narth Warahniica 


This will open a blank Location Card. Assign a Code and Name. 


Location Card 


Zones =) Bins & Inventory Posting Setup T$ Warehouse Employees & Online Map & Dimensions °°: 


General 


Code Exclude from Tax Calc... @ 


Name Tax Area Code 


Use As In-Transit @ Tax Exemption No. 


UPDATING 


Open a Location Card from the Locationss list and adjust the Name field. 
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DELETING 


Select the Manage button in the Action Bar from the Locations list and choose the Delete 
action. Note that if there are transactions for the Location, you may not be able to delete the 
Location. 


Bound Actions 


No bound actions. 


Navigations 


e countryRegion (page 402) 


History 


Version [Version Changes |... 


18.1 Endpoint added. 
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Chapter 62: Gen. Product Posting Groups 


In Business Central, when goods and services are bought and sold, which general ledger 
accounts are used for sales and purchases is handled via a combination of General Business 
Posting Group and General Product Posting Group. Curiously, this half of the configuration 
setting is made available via the API, but not the other (which would be on the Customer and 
Vendor endpoints). 


Primary Key 


Code The identifier of the General Product Posting Group. The field is 10 
characters and alphanumeric. 


Field Map 


API JSON: 
{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({ {companyID}}) /generalProductPostingGroups/ 
Sentaty', 


"Qodata.etag": "W/N"JzE5OzQ2NzcxNDMIOTEwMjUwMTkxNzAxOzAwOyc-N"", 
"id": "d2562523-df3a-edll-bbae-6045bd8e554a", 


acoden M NO WAT, 
"description": "Miscellaneous without tax", 
"defaultVATProductPostingGroup": "", 


"autoInsertDefault": true 


BUSINESS CENTRAL ENTITY: 
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General Product Posting Groups 


Ø Search + Ne Ex Edit List [i] Delete yh More options 


Def. VAT Prod. Posting 
Description Group Default 


MANUFACT : Capacities 


B 


NO TAX Miscellaneous without tax 
RAW MAT Raw materials 


Sessa 


RETAIL Retail 
SERVICES Resources, etc. 


B 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/generalProductPostingGroups 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/generalProductPostingGroups (d2562523-df3a-ed11-bbae- 
6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /generalProductPostingGroups" 
tà 

"value": [ 


{ 


"Qodata.etag": "W/N"JzE5OzQ2NzcxNDMIOTEwMjUwMTkxNzAxOzAwOyc-N"", 
"id": "d2562523-df3a-edll-bbae-6045bd8e554a", 


Neocles EE NORTA 
"description": "Miscellaneous without tax", 
"defaultVATProductPostingGroup": "", 


"autoInsertDefault": true 


"Qodata.etag": "W/N"JzE5OzQ2Nzc3NTczMjE2NTYxNjMxMzIxOzAwOyc-N"", 
"id": "d3562523-df3a-edll-bbae-6045bd8e554a", 

"code": "BRITATEM, 

“deseriperon" eV Retail 

"defaultVATProductPostingGroup": "", 

"autoInsertDefault": true 


}, 
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CRUD Steps 


CREATING 


The General Product Posting Groups list in Business Central is directly editable. So, open 
the list and create a new line. 


General Product Posting Groups vV Saved 


LD Search + New Ex Edit List li] Delete P Setup | More options 


Def. VAT Prod. Posting Auto Insert 
Code Î Description Group Default 


MANUFACT : Capacities 


8 


NO TAX Miscellaneous without tax 
RAW MAT Raw materials 

RETAIL Retail 

SERVICES Resources, etc. 


Gat 


a 


UPDATING 


The General Product Posting Groups list in Business Central is directly editable. So, open 
the list and change a line, such as the Description field. 


DELETING 


The General Product Posting Groups list in Business Central is directly editable. So, open 
the list and delete a line. 


Bound Actions 


No bound actions. 


No navigations. 


History 


| Version Changes 
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Chapter 63: Inventory Posting Groups 


Inventory Posting Groups are used on Items to drive which Inventory Accounts should 
hold the value of the stock. 


Primary Key 


Code The identifier of the Inventory Posting Group. The field is 10 characters 
and alphanumeric. 


Field Map 


API JSON: 
{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/inventoryPostingGroups/Senti 
EGY, 

"Qodata.etag": "W/\"JzIwOzExMjQ2MDczMzM4NDU4NzZMwNjg4MTswMDsn\"", 

"id": "d315971e-df3a-edl1-bbae-6045bd8e554a", 

Weodel URE SALEM, 

"description": "Resale items" 


BUSINESS CENTRAL ENTITY: 
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Inventory Posting Groups v/ Saved [] 


D Search + Ne EX Edit List ^ [W Delete More options 2 Y 


Description 


> FINISHED : Finished items 
RAW MAT Raw materials 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]))/inventoryPostingGroups 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/inventoryPostingGroups (d315971e-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /inventoryPostingGroups", 
"value": [ 


{ 
"Qodata.etag": "W/N"JzIwOzExMjO2MDczMzMANDUANzMwNjg4MTswMDsnN"", 


"id": "d315971e-df3a-edll-bbae-6045bd8e554a", 
"code"; "RESALE", 
"description": "Resale items" 


"@odata.etag": "W/N"JzIwOzExMjQ2MDYwNTg4MjA3ODMANDkS5MTswMDsnV"" , 
"id": "0p53d18a-df3a-edll-bbae-6045bd8e554a", 

coc MU ENSNHSSEIBISI 
"description": "Finished items" 


), 


CRUD Steps 


CREATING 


The Inventory Posting Groups list in Business Central is directly editable. So, open the 
list and create a new line. 
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Inventory Posting Groups vV Saved 


P Search -+ New Ex Edit List lii] Delete a Setup | More options 


Code Î Description 


> FINISHED : Finished items 
RAW MAT Raw materials 


UPDATING 
The Inventory Posting Groups list in Business Central is directly editable. So, open the 
list and change a line, such as the Description field. 
DELETING 


The Inventory Posting Groups list in Business Central is directly editable. So, open the 
list and delete a line. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


History 


| Version Changes 


19.0 Added. 
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PART 6: PROJECT AND HR 


In this Part, there are only a limited number of endpoints available, but the Time 
Registration endpoint is of particular use to time-based billing and costing organizations. 
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Chapter 64: Employees 


The Employee is the main record of the Human Resources area of the system. 


Primary Key 


No. The identifier of the Employee. The field is 20 characters and 
alphanumeric. 


Field Map 


API JSON: 


1 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/employees/Sentity", 
"Qodata.etag": "W/\"JzIwOzE1ODc2MzYzNDMONDgwOTMIMTg5MTswMDsn\"", 
"id": "1ec3a841-df3a-ed1l1-bbae-6045bd8e554a", 


"number": "EH", 

"displayName": "Ester Henderson", 
"givenName": "Ester", 
"middleName": "", 

"surname": "Henderson", 

uobi tlen: "Seeretary', 
"addressLinel": "677 Fifth Avenue", 
"addressLine2": "", 

rents Bu 

cue 3 vule 

counts de 

noo ode Eu 

"phoneNumber": "4465-4899-4643", 
"mobilePhone": "4564-4564-7831", 
mamaril s i240 

"personalEmail": "eh@cronus-demosite.com", 
"employmentDate": "2001-06-01", 
Vrerminat ton Wate 00/0] 0] 
sitas “Activen, 

HiggiaelMDeiee’s Wl on ile 2u 
VisitawlstvesGuoupeedel unm 


"lastModifiedDateTime": "2022-09-23T01:30:18.0832" 


BUSINESS CENTRAL ENTITY: 
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LT - Lina - Townsend 


Home Employee 


General 


More options 


No 

First Name 
Middle Name 
Last Name 
Job Title 


nitials 


Address & Contact 


qivenName 
middleName 
surname 


jobTitle 


m 
K 


LTOWNSENO 


Search Name 
Gender 

Company Phone No. 
Company Email 
Last Date Modified 


Privacy Blocked 


phoneNumber 


email 


lastModifiedDateTime 


Address 2 

City 

State 

ZIP Code 
Country/Region Code 


Show on Map 


Administration 


addressLinel 


addressLine2 


state 
postalCode 


countr 


Private Phone No. 
Pager 

Extension 

Direct Phone No 
Private Email 

Alt dress Code 

Alt. Address Start Date 


Alt. Address End Date 


phoneNumber 


Employment Date 
Status 

Inactive Date 

Cause of Inactivity Code 


Termination Date 


Personal 


employmentDate 


status 


terminationDate 


Grounds for Term. Code 
Emplymt. Contract Code 
Statistics Group Code 
Resource No. 


Salespers./Purch. Code 


Birth Date 


Social Security No. 


Payments > 


ü 
p. 
e 


birthDate 


Union Code 


Union Membership No 
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GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID])])/employees 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /employees (lec3a841-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (1 entity shown from a longer list): 


{ 


"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadatafcompanies ({ {companyID}}) /employees", 
"value": [ 


{ 
"Qodata.etag": "W/N"JzIwOzEl1ODc2MzYzNDMONDgwOTM1MTg5MTswMDsnN"", 


"id": "lec3a841-df3a-ed11-bbae-6045bd8e554a", 


"number": "EH", 

"displayName": "Ester Henderson", 
"givenName": "Ester", 
"middleName": "", 

"surname": "Henderson", 
"jobTitle": "Secretary", 
"addressLinel": "677 Fifth Avenue", 
"addressLine2": "", 

Leib Va: 

Inscite nu 

W(exey bau ea e ME 

"postaleodet--u mu 

"phoneNumber": "4465-4899-4643", 
"mobilePhone": "4564-4564-7831", 
Temari: iu 

"personalEmail": "eh cronus-demosite.com", 
"employmentDate": "2001-06-01", 
VErerminatvonDate: O9 OQ 
I sttausa Ate el, 

MopliaelnDenee n - Wale sqb 
WokatloenesGroupeodeles uly, 


WlastModi fiedDateTime™; “2022-09-23 700: 30718 0832" 
}, 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/employees 


Example POST Request Body: 


{ 
"number": "DP", 
"givenName": "David", 
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Niswenamem- esum 
Jioc S. WIL 2c ocho 
Wierobinicieyals: UE 


Example POST Response: 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/employees/Sentity", 

"Qodata.etag": "W/\"JzZE50z05MzYwMj YxMTO4NDE5NDczODcxOzAwOyc=\"", 

Ug eU EETIO Sad R6bbedilit8cí365-090/03989dc652 

"humber": UUDET 

"displayName": "David Pliskin", 

"givenName": "David", 

"middleName": "", 

“surcnramete APIS 

JUS Oleeaie dk e B RUE 

"addressLinel": "", 

"addressLine2": "", 

Wie al ean: mun 

"atate": Uu 

V exenpbguess sa B: MORS 

"postalcodet: wu 

"phoneNumber":; "", 

"mobilePhone": "", 

"amail": ur 

persona lEmai W uw 

"employmentDate": "0001-01-01", 

nterminac r onpate s: t OUO RN 

ustatust: Active, 

NoniceimbDeieets MOTZ- PO 

vstat ls tuesGroupCode) uM 

WiaseModitredDatel ime 5 A022 — qp NINOS 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /employees (££193a61-f£655-ed11-8c36-000d3a8dcc52) 


Example PATCH Request Body: 


"middleName": "Solid", 

"jobTitle": "Special Assignments", 
"addressLinel": "Shadow Moses Island", 
"email": "David@Pliskin.com", 
"personalEmail": "Keptyou@waiting.huh", 
"employmentDate": "1995-04-30", 
"status Actu vet 


Example PATCH Response: 
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"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({{companyID}})/employees/Sentity", 

"Qodata.etag": "W/\"JzIwOzEOMTAyNDE4OTOSNzcyNzIINTUyMTswMDsn\"", 

Tron Wie LC) seiGil eGo Schill se SOOO Wcliatiches24 


"umber" 8 Ww ipie. 

"displayName": "David Pliskin", 
"givenName": "David", 

"middleName": "Solid", 

"surname MUT Sem 

"jobTitle": "Special Assignments", 
"addressLinel": "Shadow Moses Island", 
"addressLine2": "", 

rese Us UA 

"staten: M 

eoun avaa WES 

Vooswaleode iy, 

"phoneNumber": "", 

"mobilePhone": "", 

"email": "David@Pliskin.com", 
"personalEmail": "Keptyou@waiting.huh", 
"employmentDate": "1995-04-30", 
"terminationDate": "0001-01-01", 
ustatus t: Acte, 

WopkicielaDyeier OG dia 

Insiearsibdie soupe ode 
“astModiimiedDacenime t VA0 2202 7:203 2:8 599 B IE 3/5 07:5) S4 9 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /employees (££193a61-f£655-ed11-8c36-000d3a8dcc52) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


In the Employees list, click on the New button in the Action Bar: 
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Employees 


P Search + New Manage 4e Absence Registration 2 Pay Employee Æ Contact Eg Ledger Entries E Send I 


Henderson 


Ester Secretary ' i Sales Manager 


Townsend à Horst 
Designer  * i Marty Production Assistant 


n Bettencourt 
Managing Director  * Robin Production Manager 


Production Assistant 


This will open a blank Employee Card. Click in the First Name field (which should 
automatically assign an Employee No. — if not, enter an Employee No. manually) and enter text: 


Employee Card 
E0020 


Home Employee Navigate More options 


335 Pay Employee E Send Email 


General Show more 


No. EE Initials 


First Name Search Name 


Middle Name Gender Female 


Last Name Company Phone No. 


Job Title Company Email 


UPDATING 


Open an Employee Card from the Employees list and adjust the Name field. 


DELETING 


Select the Manage button in the Action Bar from the Employees list and choose the Delete 
action. 
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Bound Actions 


No bound actions. 


e countryRegion (page 402) 

e picture (page 453) 

e defaultDimensions (page 417) 

e timeRegistrationEntries (page 370) 


No notable changes. 
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Chapter 65: Projects (Jobs in BC) 


The Jobs area of Business Central allows to manage and bill for use of Resources, Items, 
and such. The Job record is the main record of this area, though it is exposed as the Project 


endpoint. 
Primary Key 
No. The identifier of the Job. The field is 20 characters and alphanumeric. 
Field Map 
API JSON: 
{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 


/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/projects/Sentity", 
"@odata.etag": "W/N"JzIWOzExMjO2MDY1MTExNDIyNzg4NTkzMTswMDsnN"", 
"id": "A49ed162f-df3a-edll1-bbae-6045bd8e554a", 

"number": "JOB00010", 
"displayName": "Reception area remodel" 


BUSINESS CENTRAL ENTITY: 
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Job Card £ 


JOBO00010 - Reception area remodel 


Home Print/Send Prices & Discounts WIP Job Report 


General 


No number se Person Responsible 
Description displayName Blocked 
Customer Name School of Fine Art Last Date Modified 


External Document No. Project Manager 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} } /APIBook/api/v2.0/companies( 
{company|D}}) / projects 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/projects (49ed1 62 f-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 


"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/projects", 
"value": [ 
{ 


"@odata.etag": "W/N"JzIwWOzExMjO2MDY1MTExNDIyNzg4NTkzMTswMDsnN"", 
"id": "49ed162f-df3a-edll-bbae-6045bd8e554a", 

"number": "JOB00010", 
"displayName": "Reception area remodel" 


"Qodata.etag": "W/N"JzIwOzExMjO2MDY1MDQzNTA5OTcC2MTgwMTswMDsnN"", 
"id": "4aed162f-df3a-edll-bbae-6045bd8e554a", 

"number": "JOB00020", 

"displayName": "Decorate Conference Room" 


"Qodata.etag": "W/N"JzIwOzExMjO2MDYOOTCINTCONDA2OTAyMTswMDsnN"", 
"id": "4bed162f-df3a-edll-bbae-6045bd8e554a", 
"number": "JOBO00030", 
"displayName": "New Office Furniture" 
), 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]])/projects 


Example POST Request Body: 


"number": "JOB00040", 
"displayName": "Writing Selfbiography" 


Example POST Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/projects/Sentity", 
"@odata.etag": "W/\"JzIwOzExMjQ2MDY1NDY2NDk5MjMyOTYzMTswMDsn\"", 
"id": "0da668e4-f655-ed11-8c36-000d3a8dcc52", 
"number": "JOB00040", 
"displayName": "Writing Selfbiography" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]]))/projects (0da668e4-f£655-ed11-8c36-000d3a8dcc52) 


Example PATCH Request Body: 


"displayName": "Handling Paperwork" 


Example PATCH Response: 


{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/projects/Sentity", 
"Qodata.etag": "W/N"JzIwOzExMjO2MDY1NDY2MzM1NjAOODEAMTswMDsnN"", 
"id": "0da668e4-f655-ed11-8c36-000d3a8dcc52", 
"number": "JOB00040", 
"displayName": "Handling Paperwork" 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}})/projects (0da668e4-f£655-ed11-8c36-000d3a8dcc52) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


In the Jobs list, click on the New button in the Action Bar: 


Jobs 


2 Search + New Manage Home Report Navigate Job Prices & Discounts 


No. f Description Bill-to Customer No. Status 
JOB00010 : Reception area remodel Open 
JOB00020 Decorate Conference Room Open 


JOB00030 New Office Furniture Open 


This will open a blank Jobs Card. Click in the Description field (which should automatically 
assign a Job No. - if not, enter a Job No. manually) and enter text: 


Job Card 


Home Print/Send Prices & Discounts WIP More options 


3 Copy Job Tasks from... [£l Copy Job Tasks to... 


General 


No oe Person Responsible 


Description Blocked 


Customer Name * Last Date Modified 


External Document . Project Manager 


Tasks Manage Line Fewer options 


Job Task Budget (Total 
Job Task No Description Type Start Date End Date 
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UPDATING 


Open an Job Card from the Jobs list and adjust the Description field. 


DELETING 


Select the Manage button in the Action Bar from the Items list and choose the Delete 
action. 


Note: if there are transactions for the Job, you may not be able to delete the Job. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


History 


No notable changes. 
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Chapter 66: Time Registration Entries 


The Time Registration Entries endpoint works on top of the Time Sheet system in Business 
Central. 


The Time Sheet system is built around the time entries of a Resource, not Employees, 
though Absence registration from the Time Sheet goes to an Employee, not a Resource. 


The Time Sheet system in Business Central supports registering time against: 


e Resource. 
e Job. 

e Service. 

e Absence. 
e Assembly. 


This endpoint, however, only supports the Resource type line entries. 


Additionally, it is important to understand the design of the Time Sheet system: 


NE SA What Time range 
Header * Which Resource 


EO SNA Which type of time 
Line *Descriptive Info 


Time Sheet hich Date 
e What 


Detail Quantity 


This endpoint mixes information from all three levels, plus adds related information from 
the Employee that is connected to the Resource in question. This is done by combining 
information into an aggregated table, making the usual "Primary Key" information irrelevant. 
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This endpoint also has some confusing information, namely, the Job and Absence related 
fields, and a variety of problems. 


Job Fields 


Curiously, you will never get any Lines on a GET call to this endpoint that will have a Type 
of Job. This means that if you register time correctly in Business Central to a Job Type line, it 
will be invisible to this endpoint. 


However, the endpoint will accept values in POST / PATCH calls in these values. 
Frighteningly, this will manufacture malformed data. The Time Sheet Detail will be marked of 
type Resource, with the relevant jobId/jobNumber/JobTaskNumber fields you specify. The 
Time Sheet Line will display a type of Resource with none of the correct information. Posting 
will not function correctly. 


Absence Field 


This field is even less utility. You will never see results with an Absence Code, and if you 
try to POST / PATCH to it, it will result in an error since absence is a read only field. 


Date Field — Cautionary Notice 


The date field is designed to assist the endpoint in locating which Time Sheet Header 
should be used, as well as note the specific Date of the time usage on the Time Sheet Detail. 


However, if there is no matching Time Sheet Header that encompasses the date in 
question, rather than giving an error message, it will create a new Time Sheet Header for the 
Resource in question, with no indication it has done so. The only constraint on this appears to 
be if an open Accounting Period exists, which can lead to a confusing error to the endpoint: 


{ 


em cor ME 
"code": "Application FieldValidationException", 
"message": "Closed must be equal to 'No' in Accounting Period: Starting 
Date-05/01/03. Current value is 'Yes'. CorrelationId: 4b8b9897-227f£-4f51-80f5- 
3e4065b63c06." 


} 
} 


Date Filtering 


Be aware that there is no endpoint that gives a list of the current Time Sheet Headers 
open in the system, so you cannot determine which dates to use for filtering on a per-Time 
Sheet basis. 


Primary Key 


See above. This is an aggregated table. 
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Field Map 


API JSON: 


{ 


"@odata.context": 


"https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 


/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /timeRegistrationEntries/S$ent 


Liew, 
"@odata.etag": "W/\"JzIwOzE1MjczOTYwNzU5NzZE3NjE1Mzk3MTswMDsn\"", 
"id": "06a4cf89-e094-ed11-bff£5-00224803bb96", 
"employeeId": "21c3a841-df3a-edll-bbae-6045bd8e554a", 
"employeeNumber": "MH", 
"JobId": "00000000-0000-0000-0000-000000000000", 
"jobNumber": "", 
"jobTaskNumber": "", 
"5bsence™: nu 
"lineNumber": 40000, 
Widleiee sume O22) Oa 
couant eyes 74, 
stats Opens 
"unitOfMeasureId": "del15971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "HOUR", 
"lastModfiedDateTime": "2023-01-15T14:26:03.4332" 


BUSINESS CENTRAL ENTITY: 


The information comes from multiple sources, as outlined in this table: 


employeeld / The GUID / Alphanumeric key to the Employee. This is 

employeeNumber connected via the Employee Card, the Resource No. 
field. 

jobld / jobNumber The GUID / Alphanumeric key to the Job. 
Non-functional, see above. 

jobTaskNumber The alphanumeric key of the Job Task table, the Job Task 
No., connected to the Job. 
Non-functional, see above. 

absence In theory, this is connected to the Cause of Absence list. 
Non-functional, see above. 

lineNumber This is the integer Line Number of the Time Sheet Line. 

date The Date on which the time should be performed. 
Functional, but see above cautionary notice! 

quantity Typically, this is the hours worked, though that is 
determined by the Unit of Measure. As such, there is no 
constraints on this field, and 8 is as valid as -8000000. 

status This aligns to the Status Field of the Time Sheet Line. This 
is non-editable from the endpoint. 

unitOfMeasureld / This displays the Base Unit of Measure from the Resource 

unitOfMeasureCode Card. 

Id This GUID is the systemld of the Time Sheet Detail. 
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GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /employees (lec3a841-df3a-ed11-bbae- 
6045bd8e554a) /timeRegistrationEntries 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /employees (lec3a841-df3a-ed11-bbae- 
6045bd8e554a) /timeRegistrationEntries (fff37210-£855-ed11-8c36-000d3a8dcc52) 


Example GET Response (2 entities shown from a longer list): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadatafcompanies(((companyID]]) /employees (lec3a841-df3a- 
edil-bbae-6045bd8e554a)/timeRegistrationEntries", 

"value": [ 


{ 


"Qodata.etag": "W/N"JzE3OZzEXxODC3MzYA4NjOzNjkyNjkzMTswMDsnN"", 
Ng Ute EE ecl 9e 900 cie aoc 
"employeeId": "1ec3a841-df3a-edl1-bbae-6045bd8e554a", 


"employeeNumber": "EH", 

"jobId": "00000000-0000-0000-0000-000000000000", 
"jobNumber": "", 

"jobTaskNumber": "", 

"absence"; "", 


"lineNumber": 10000, 
vda cenci A022 (OI (0A T 
JienicWanbsLiES/ S Gp 


WewccnEDIS Mg. AOpen, 
"unitOfMeasureId": "del5971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "HOUR", 


DasuMceciuesiatserngmes-22029- 0-9] y] 9:55 0 90) Jt 


"Qodata.etag": "W/N"JzE5OzO3NzgxOTIOOTAOODUZzODU2NZQxOzAwOyc-N"", 
Weis uoee5slle ES5bzedii-96936-09)0/0&d928dc66527 
"employeeId": "1ec3a841-df3a-edl1-bbae-6045bd8e554a", 


"employeeNumber": "EH", 

"jobId": "00000000-0000-0000-0000-000000000000", 
"jobNumber": "", 

"jobTaskNumber": "", 

"absence"; "", 


"lineNumber": 10000, 
dacen: 2029 T9097 
gouant eye O 


siat NN ODonw 
"unitOfMeasureId": "del15971e-df3a-edl1-bbae-6045bd8e554a", 
"unitOfMeasureCode": "HOUR", 


"lastModfiedDateTime": "2022-10-27T13:06:05.6232Z" 
), 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /employees (lec3a841-df3a-ed11-bbae- 
6045bd8e554a) /timeRegistrationEntries 


Example POST Request Body: 


"employeeNumber": "EH", 
Vidette O27 lO Rue 
ligiiiciaiciney ye A 


Example POST Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID]) 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /employees(1ec3a841-df3a- 
ed11-bbae-6045bd8e554a) /timeRegistrationEntries/Sentity", 

"@odata.etag": "W/N"JzIWOzE3MDkyMzA1MDMxMDEOMjAyMzAxMTswMDsnN"", 

"id": "2e72356f-f855-ed11-8c36-000d3a8dcc52", 

"employeeId": "1ec3a841-df3a-edll-bbae-6045bd8e554a", 


"employeeNumber": "EH", 

"jobId": "00000000-0000-0000-0000-000000000000", 
"jobNumber": "", 

"jobTaskNumber": "", 

"absence"; "", 


"lineNumber": 10000, 
dacen POTETE 
WieiiicioncaneyvS vio 


WStacustics Open, 

"unitOfMeasureId": "del5971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "HOUR", 

"lastModfiedDateTime": "2022-10-27T713:08:25.3472" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /employees (lec3a841-df3a-ed11-bbae- 
6045bd8e554a) /timeRegistrationEntries (2e72356f-£855-ed11-8c36-000d3a8dcc52) 


Example PATCH Request Body: 


"jobNumber": "JOB00020", 
JeuievedbdLiES7 E. S 


Example PATCH Response: 
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{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadatafcompanies ({ {companyID}}) /employees (lec3a841-df3a- 
ed11-bbae-6045bd8e554a) /timeRegistrationEntries/Sentity", 

"@odata.etag": "W/\"JzIwOzEwMjMINzk2MTg2NTA2NjMzNTUSMTswMDsn\"", 

Widity Ze 23 560£-E655—-edl l—se36_000dsaddecs2, 

"employeeId": "1ec3a841-df3a-edll-bbae-6045bd8e554a", 

"employeeNumber": "EH", 

"jobId": "4aed162f-df3a-edll1-bbae-6045bd8e554a", 

"jobNumber": "JOB00020", 

"jobTaskNumber'": "" 

"5bsence™: Uo 

"lineNumber": 10000, 

JhglewereMa- UII TE d 

euam teya 


"status open" 

"unitOfMeasureId": "del5971e-df3a-edll-bbae-6045bd8e554a", 
"unitOfMeasureCode": "HOUR", 

"lastModfiedDateTime": "2022-10-27T13:10:42.412" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /employees (lec3a841-df3a-ed11-bbae- 
6045bd8e554a) /timeRegistrationEntries (2e72356f-£855-ed11-8c36-000d3a8dcc52) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


Configuration and creation of Time Sheets is beyond the scope of this book, but to create 
a Time Sheet Line / Detail to see in the API, create a Time Sheet line of Type Resource, then 
enter a Quantity into a column. 
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Time Sheet 


April 18, 2022 (Week 16) 


Home Prepare More options 


@ Reoper [2 Submit GJ Comments 


General 


Resource No. 


Manage Line Fewer options 


Type Status Description 18 Mon 19 Tue 20 Wed 21 Thu 


> Resource $ — Open 2 


UPDATING 
Change an existing Quantity column value. 
However, note that with the way the time sheet architecture works, if a user clears a 
quantity field (to zero or blank), then re-enters a quantity in that same column, it removes and 
creates a new Time Sheet Detail entry, so the id field will change. 


DELETING 


Clear a Quantity field (to zero or blank). 


Bound Actions 


No bound actions. 


e employees (page 358) 

e projects (page 365) 

e unitsOfMeasure (page 471) 

e dimensionSetLines (page 427) 


History 


No notable changes. 
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PART 7: VARIOUS 


In this Part, many of these endpoints are used throughout the rest of the API, from simple 
information endpoints, like Company Information, to the much more complex, like the 
Attachments endpoint. 
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Chapter 67: Attachments 


This endpoint can frequently cause a great deal of confusion, and with some good reason. 
For example, on this Sales Order, locate the Attachments area: 


Sales Order 
S-ORD101001 - Adatum Corporation 
Home Prepare Print/Send Request Approval Order Report Actions Related Automate Fewer options 
E Copy Document E) Get Recurring Sales Lines. Incoming Document [i Calculate Invoice Discount ffi Move Negative Lines. 7i Predict Payment 


General dmn: © Details — 0) Attachments (0) 


Adatum Corporation m 5/2/2022 Sell-to Customer Sales History 


Robert Townes s. Requested Delivery D 4/3/2022 Customer No. 10000 


4/2/2022 


4/2/2022 


If you noticed the part labelled “Attachments” in the FactBox on the right, you have 
experienced the same confusion. 


The Attachments endpoint is connected to the Incoming Document subsystem, not the 
system FactBox part “Attachments”. This FactBox part has its own endpoint, Document 
Attachments, and is described in Chapter 68: Document Attachments (page 387). 


Another area of confusion is that Attachment operations typically consist of two steps: 


e GET /GET - first call to find the relevant Incoming Document record and ld fields, 
and second call to get the content (document, image, etc.) 

e POST / PATCH - first call to create an Incoming Document record and, using the 
Id fields from the results, to PATCH the content (document, image, etc) 


Primary Key 


This Attachment endpoint is a buffer table that looks up and writes back information from 
multiple tables. 


Depending on the parentType filter, the parentId will be a GUID lookup to the 
systemld of any of: 
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e Sales Documents (Quotes, Orders, Invoices, Credit Memos). 
e Purchase Documents (Order, Invoice). 

e General Journals. 

e G/L Entries. 


Field Map 


API JSON: 


This one is complex and multi-part. Depending on the operation types, you will have 
different information. When dealing with the first step, the API body will look like the following: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/attachments/Sentity”, 

"Qodata.etag": “W/\”JzIwOzEONDOZMDE3MDgwNDUyMzYwNjJEyMTswMDsn\"”, 

"id": “4f186ed9-c198-ed11-bff5-6045bd02a4b4”, 

"parentId": "fbale334-3055-ed11-8c36-000d3a8dc661", 

“fileName”: “BCLogo.png”, 

Spytesize”: 0, 

"lastModifiedDateTime": "2023-01-20T12:56:352", 

PeEneeneuwassUs Seules sx0(02(0/ (Oxseleuz 7 7 

"attachmentContentGodata.mediaEditLink": "https://api.businesscentral.dynamic 
s.com/v2.0/((tenantID]))/APIBook/api/v2.0/companies(((companyID)])/attachments (4f1 
86ed9-c198-ed11-bff5-6045bd02a4b4)/attachmentContent", 

"attachmentContent8üodata.mediaReadLink": "https://api.businesscentral.dynamic 
s.com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}}) /attachments (4f1 
86ed9-c198-ed11-bf£5-6045bd02a4b4) /attachmentContent” 
} 


BUSINESS CENTRAL ENTITY: 
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Incoming Document 


Relecloud 


Home Prepare Request Approval Incoming Document More options 


fim Create Manually — 1^ Fa V Release Vv se 


General 


Description | Relecloud 


Main Attachment BCLogo.png 


Record Sales Order - S-ORD101006 


Status New 


There is no visible version of many of the API fields, which is part of the challenge of 
working with this endpoint. Even the parent field marked is not precisely shown in the API, 
instead it is the parentType and parentId fields. 


Another key understanding here is that the Incoming Document response body has two 
links as values, one to access the current contents of the file 
(attachmentContent@odata.mediaReadLink) and the other to alter the contents of the 
file (attachmentContent@odata.mediaEditLink). With these links, you can issue GET or 
PATCH calls. 


GET 


To get an Incoming Document, you need to filter the attachments on either: 


e TheattachmentId, the unique Guid of the Incoming Document record. 
e The parentType and parentId (unique GUID of the related record) that the 
Incoming Document is attached to. 


Valid parentType values are: 


e Sales Quote. 

e Sales Order. 

e Sales Invoice. 

e Sales Credit Memo. 
e Purchase Order. 

e Purchase Invoice. 
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e Journal. 


The following is an example of getting the Incoming Document record for a Sales Order: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.@/companies({c 


ompanyID}})/attachments?$filter=(parentType eq ‘Sales Order’) and (parentId eq fba1e334- 
3055-ed11-8c36-000d3a8dc661) 


This will get an Incoming Document record as follows: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/attachments”, 

“value”: [ 


{ 


“@odata.etag”: “W/\"”JzIwOzEONDQZMDE3MdgyMjM1IMTgOMDAOMTswMDsn\"”, 

“id”: “4£186ed9-cl98—edll—bf£t5-6045ba02a4b4”, 

"parentId": "fbale334-3055-ed11-8c36-000d3a8dc661", 

“fileName”: “BCLogo.png”, 

"byteSize": 27287, 

"lastModifiedDateTime": “2023-01-20T12:56:362”, 

“ocr emrys A "erue 0020) Orce 

“attachmentContent@odata.mediaEditLink”: "https://api.businesscentral 
.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}})/attachm 
ents(4f186ed9-c198-ed11-bff5-6045bd02a4b4)/attachmentContent", 

“attachmentContent@odata.mediaReadLink”: "https://api.businesscentral 
.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}}) /attachm 
ents (4£186ed9-c198-ed11-bf£5-6045bd02a4b4) /attachmentContent” 

} 


] 


You can then use GET to fetch the /attachmentcontent, which is a binary stream (an 


application/octet-stream, not a Base64 string) using the attachment record's ID to filter on, as 
follows: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/attachments (4£186ed9-c198-ed11-bff5- 
6045bd02a4b4) /attachmentContent 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/attachments 


Example POST Request Body: 


"parentType": "Sales Order", 
"parentId": "fbale334-3055-ed11-8c36-000d3a8dc661", 
“fileName”: “BCLogo.png” 


Example POST Response: 
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1 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/((tenantID])] 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/attachments”, 
“value”: [ 
{ 
"Qodata.etag": “W/\”JzIwOzEONDOZMDE3MDgyMzQ30DI2NDYxMTswMDsn\”"”, 
"id": "4f186ed9-c198-ed11-bff5-6045bd02a4b4", 
"parentId": "fbale334-3055-ed11-8c36-000d3a8dc661", 
“fileName”: “BCLogo.png”, 
"byteSize": 0, 
“lastModifiedDate Lime”: \2Z023-01—20T1L2 5673162", 
Yperen g Saec MGE 
"attachmentContentGodata.mediaEditLink": "https://api.businesscentral 
.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}}) /attachm 
ents (4£186ed9-c198-ed11-bff£5-6045bd02a4b4) /attachmentContent”, 
‘“attachmentContent@odata.mediaReadLink”: "https://api.businesscentral 
.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}}) /attachm 
ents (4£186ed9-c198-ed11-bf£5-6045bd02a4b4) /attachmentContent” 
} 


] 


PATCH 


Typically, you would only use a PATCH call to add the file content to the attachment via 
the /attachmentContent path. The only field you can patch on the main record is the 
fileName value. 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/attachments (4f186ed9-c198-ed11-bff5-6045bd02a4b4) 


Example PATCH Request Body: 


“fileName”: “Business Central Logo.png” 


Example PATCH Response: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /attachments/Sentity”, 

"Qodata.etag": “W/\”JzIwOzExNTE4NTOINTOWNzgOMTk4MzkzMTswMDsn\"", 

"id": "4f186ed9-c198-ed1l1-bff5-6045bd02a4b4", 

"parentId": "fbale334-3055-ed11-8c36-000d3a8dc661", 

“fileName”: "Business Central Logo.png”, 

Dpytesize -27287 

XlaseModitiriedDatetime n: \2023 09] 20 1] 95/92: 919/147 

Soenens A Meeles sx0(02(0/ Orcera 

“attachmentContent@odata.mediaEditLink”: "https://api.businesscentral.dynamic 
s.com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}})/attachments (4f1 
86ed9-c198-ed11-bff5-6045bd02a4b4)/attachmentContent", 

"attachmentContent8üodata.mediaReadLink": "https://api.businesscentral.dynamic 
s.com/v2.0/((tenantID]))/APIBook/api/v2.0/companies(((companyID)])/attachments (4f1 
86ed9-c198-edl11-bff5-6045bd02a4b4)/attachmentContent" 
} 
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When you PATCH to the /attachmentContent endpoint, you would use the Id of the 
attachment, and the body is the file itself. An example URI would be: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/attachments (4£186ed9-c198-ed11-bff5- 
6045bd02a4b4) /attachmentContent 


On the PATCH request, you need to specify in the HEADERS that this should be 
Content-Type: application/octet-stream, and data should be sent as such. 


No response body will be given, only an HTTP Status of 204, "No Content". 


DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/attachments (4f186ed9-c198-ed11-bff5-6045bd02a4b4) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". You are not required to delete the content separately. 


CRUD Steps 


CREATING 


One of the most common ways to add an Incoming Document is to add an existing file 
to a Sales or Purchase Document. 


On a Sales Order, locate the Create Incoming Document from File... action: 
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Sales Order 


S-ORD101003 - School of Fine Art 


Home Prepare Print/Send Request Approval Order Report Actions w Related ^» Aut 


E Copy Document... Eal Get Recurring Sales Lines... Incoming Document v [à Calculate Invoice Disc 


Ù Create Incoming Document from File... 
General 


a 


Customer Name School of Fine Art ,. . e Date 
— — — ——— Bil Select Incoming Document 


Contact Meagan Bond g quested | 
wx nt 


Posting Date 4/22/2022 E] External Do 


Order Date 4/22/2022 i Status 


This will allow you to select a file to attach (as an Incoming Document). Once you have 
completed the attachment selection, you will receive a notification that it worked. From there, 
you can locate the View Incoming Document action to verify it worked: 


Sales Order 


S-ORD101003 - School of Fine Art 


X The action to create an incoming document from file has completed. 


Home Prepare Print/Send Request Approval Order Report Actions w Related ^» Automate 


EB Copy Document... Es) Get Recurring Sales Lines... Incoming Document v [@ Calculate Invoice Discount 


W 
General 
View Incoming Document 


Customer Name School of Fine Art |. i ie Date 
— ——— — H Select Incoming Document 


Contact Meagan Bond  , : quested Delive 
———— — — *X Remove Incoming Document 


Posting Date 4/22/2022 | External Docume! 


From the Incoming Document screen, you can click on the Main Attachment link to 
download/open the file: 
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Incoming Document 


CRONUS Purchase Invoice 108206 


Home Prepare Request Approval Incoming Document Related ^^ Automate v Fewer t 


fu Create Manually t] v/ Release | v gE) Set To Pro 


General 


Description i OCR Sei 
Link to Document OCR Se! 
Main Attachment CRONUS Purchase Invoice 108206.pdf OCR Re: 
Data Exchange Type Created 
Record Sales Order - S-ORD101003 Created 


Status Created Release: 


UPDATING 
Triggering an update is difficult, as the only editable field on the Incoming Document is 
not exposed in the API. 
DELETING 


From the Sales Order (or where you have attached an Incoming Document), locate the 
Remove Incoming Document action: 


PART 7: VARIOUS 
CHAPTER 67: ATTACHMENTS 


Sales Order 


S-ORD101006 - Relecloud 


Home Prepare Print/Send Request Approval Order Report | Actions w Related ^^  / 


EB Copy Document... Es] Get Recurring Sales Lines... Incoming Document v [à Calculate Invoice | 


Ù Create Incoming Document from File... 


General 


View Incoming Document 


Customer Name Relecloud - f ie Dat 
R Select Incoming Document 


Contact Jesse Homer 4 A quest 
———— — — 2X Remove Incoming Document 


Posting Date 4/11/2022 | External 


Order Date 4/11/2022 | Status 


Bound Actions 


No bound actions. 


e salesInvoices (page 168) 

e JournalLines (page 76) 

e generalLedgerEntries (page 59) 
e salesOrders (page 184) 

e salesQuotes (page 202) 

e salesCreditMemos (page 152) 
e purchaselnvoices (page 252) 

e PurchaseOrders (page 267) 


No notable changes. 
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Chapter 68: Document Attachments 


Document attachments are the actual attachments to documents as described in the 
previous section. 


Primary Key 


The Document Attachment endpoint is a buffer table that looks up and writes back 
information from multiple tables. 


Depending on the parentType filter, the parentId will be a GUID lookup to the 
systemld of any of: 


e Sales Documents (Quotes, Orders, Invoices, Credit Memos). 
e Purchase Documents (Order, Invoice). 

e General Journals. 

e G/L Entries. 


Field Map 


API JSON: 
{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}})/documentAttachments", 

"value": [ 


{ 
"Qodata.etag": "W/\"JzE50zU1NjcOMzcyODEZNTQOMZM3MTQxOzAwOyc=\"", 
"id": "46ba71d4-bbl6-ef11-be95-f60edc7f3ee3", 


"fileName": "Invoicel.PDF", 
"byteSize": 1474, 
Mosaics Uy O20 Ordet, 


"parentId": "28ebl13b1-ddll-ef11-9f8b-6045bde9cc61", 

"lineNumber": 0, 

"documentFlowSales": false, 

"documentFlowPurchase": false, 

"lastModifiedDateTime": "2024-05-20T15:15:46.12", 

"attachmentContent@odata.mediaEditLink": "https://api.businesscentral 
.dynamics.com/v2.0/companies(((companyID)]) /documentAttachments (46ba71d4-bb16- 
f11-be95-f60edc7f3ee3)/attachmentContent", 
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"attachmentContent@odata.mediaReadLink": "https://api.businesscentral 
.dynamics.com/v2.0/companies ({{companyID}}) /documentAttachments (46ba71d4-bb16- 
fl1l1-be95-f60edc7f3ee3)/attachmentContent" 
), 
{ 


"Qodata.etag": "W/\"JzIwOzE3NDY3MDAyMzY20DMyNTMINzA4MTswMDsn\"", 
"id": "66c9a3df-bbl6-ef11-be95-f60edc7f3ee3", 


"fileName": "invoice2.PDF", 
"byteSize": 1474, 
pscenmiepeu Mate sqb9)02(00 clc 


"parentId": "44eb13b1-ddll-ef11-9f8b-6045bde9cc61", 

"lineNumber": 0, 

"documentFlowSales": false, 

"documentFlowPurchase": false, 

WlastModt@iredDarerime™: | '2024-05-20Ti 5/2569 65544, 

"attachmentContent@odata.mediaEditLink": "https://api.businesscentral 
.dynamics.com/v2.0/companies ({{companyID}}) /documentAttachments (66c9a3df-bb16- 
f11-be95-f60edc7f3ee3)/attachmentContent", 

"attachmentContent@odata.mediaReadLink": "https://api.businesscentral 
.dynamics.com/v2.0/companies(((companyID)])/documentAttachments (66c9a3df-bb16- 
fll-be95-f60edc7f3ee3)/attachmentContent" 

] 


] 


BUSINESS CENTRAL ENTITY: 


Attached Documents 


o +New  BZEditlist [ij Delete — 4| Download 


Attachment File Extension File Type Attached Date 


> invoice2 : PDF PDF 20/05/2024 16:16 


Like the previous endpoint, there is no visible version of many of the API fields. The parent 
field marked is not precisely shown in the API, instead it is the parentType and parentId 
fields. 


Another key understanding here is that the Document Attachment response body has 
two links as values one to access the current contents of the file 
(attachmentContent@odata.mediaReadLink) and the other to alter the contents of the 
file (attachmentContent@odata.mediaEditLink). With these links, you can issue GET or 
PATCH calls. 


Example GET Request URI List: 
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https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({{companyID}}) /documentAttachments 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({{companyID}}) /documentAttachments (66c9a3df-bbl6-efll-be95-f60edc7f3ee3) 


Example GET Response (single): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}}) /documentAttachments/Sentity", 

"Qodata.etag": "W/N"JzIWOzEONZUyMTAOOTUSNjUzNzQ5MjAyMTswMDsnN"", 

"id": "66c9a3df-bbl6-ef11-be95-f60edc7f3ee3", 

"fileName": "invoice2.PDF", 

"byteSize": O0, 

Movies es syedkexs 0020 Order, 

"parentId": "44eb13b1-dd1ll-ef11-9f8b-6045bde9cc61", 

"lineNumber": 0, 

"documentFlowSales": false, 

"documentFlowPurchase": false, 

"lastModifiedDateTime": "2024-05-20T15:16:04.8532", 

"attachmentContent@odata.mediaEditLink": "https://api.businesscentral.dynamic 
s.com/v2.0/companies ({{companyID}}) /documentAttachments (66c9a3df-bb16-ef11-be95- 
f60edc7f£3ee3) /attachmentContent", 

"attachmentContent@odata.mediaReadLink": "https://api.businesscentral.dynamic 
s.com/v2.0/companies ({{companyID}}) /documentAttachments (66c9a3df-bb16-ef11-be95- 
£60edc7£3ee3) /attachmentContent" 
} 


While using the id will work in getting just one of the attachments, it is suggested to use 
the $filter method, detailed in the previous section. 


For example: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID))/APIBook/api/v2.0/companies((c 
ompanyID)))/attachments?$filter-(parentType eq ‘Sales Order?) and (parentId eq 44eb13b1- 
ddll1-ef11-9f8b-6045bde9cc61) 


This will get an Incoming Document record as follows: 


{ 


“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/$metadata#companies ({ {companyID}})/documentAttachments”, 
“value”: [ 


{ 


“@odata.etag”: "W/N"JzIwOzEONDQzMDE3MdgyMjM1MTgOMDAOMTswMDsn ^" , 

Mid’: “4t186ed9-cl98—edl l—bEE5-6045ba02a4b47, 

"parentId": "fbale334-3055-ed11-8c36-000d3a8dc661", 

“fileName”: “BCLogo.png”, 

"byteSize": 27287, 

iaseMecdhimed Dace Lime a) 0i2 ONE 2T ISI 

"senses p. "eub 0002/0) Orsa", 

"attachmentContentG8odata.mediaEditLink": "https://api.businesscentral 
.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}}) /attachm 
ents (4£186ed9-c198-ed11-bff5-6045bd02a4b4) /attachmentContent”, 

“attachmentContent@odata.mediaReadLink”: "https://api.businesscentral 
.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}}) /attachm 
ents (4£186ed9-c198-ed11-bf£5-6045bd02a4b4) /attachmentContent” ) 
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You can then use GET to fetch the /attachmentContent, which is a binary stream (an 
application/octet-stream, not a Base64 string) using the attachment record's ID to filter on, as 
follows: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/attachments (4£186ed9-c198-ed11-bff5- 
6045bd02a4b4) /attachmentContent 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /documentAttachments 


Example POST Request Body: 


"parentType": "Purchase Credit Memo", 
"parentId": "de9f5d62-b421-ef11-9467-d62465a5064f", 
"fileName": "BCLogo.png" 


Example Post Response: 


{ 

"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies (a9baaac8-9dfc-eel11-9f8c- 
6045bde98c0f) /documentAttachments/Sentity", 

"Qodata.etag": "W/N"JzE5Ozg2NjUwODczNzYyNjU2NDESNDgxOzAwOyc-N"", 

"id": "00bbc3a6-7622-ef11-9467-d62465a5064f", 


"fileName": "BCLogo.png", 
"byteSize": O0, 
"parentType": "Purchase x0020 Credit x0020 Memo", 


"parentId": "de9f5d62-b421-ef11-9467-d62465a5064f", 

"lineNumber": 0, 

"documentFlowSales": false, 

"documentFlowPurchase": false, 

"lastModifiedDateTime": "2024-06-04T13:30:48.1072", 

"attachmentContent@odata.mediaEditLink": "http://demo- 
23cu5:7048/BC/api/v2.0/companies (a9baaac8-9dfc-eel1-9f8c- 
6045bde98c0£) /documentAttachments (00bbc3a6-7622-ef11-9467- 
d62465a5064f) /attachmentContent", 

"attachmentContent@odata.mediaReadLink": "http://demo- 
23cu5:7048/BC/api/v2.0/companies (a9baaac8-9dfc-eel1-9f8c- 
6045bde98c0£) /documentAttachments (00bbc3a6-7622-ef11-9467- 
d62465a5064f) /attachmentContent" 
} 
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PATCH 


Typically, you would only use a PATCH call to add the file content to the attachment via 
the /attachmentContent path. The only field you can patch on the main record is the 
fileName value. 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)]))/documentAttachments (00bbc3a6-7622-ef11-9467-d62465a5064f) 


Example PATCH Request Body: 


"fileName": "Business Central Logo.png" 


Example PATCH Response: 


{ 

"@odata.context": "http://demo- 
23cu5:7048/BC/api/v2.0/Smetadata#companies (a9baaac8-9dfc-eel1-9f8c- 
6045bde98c0f) /documentAttachments/Sentity", 

"Qodata.etag": "W/N"JzESOzES3NzEzOTM2NDgA4NjIyNTkzNzYxOzAwOyc-N"", 

"id": "00bbc3a6-7622-ef11-9467-d62465a5064f", 


"fileName": "BCLogo.pngBusiness Central Logo.png", 
"byteSize": O0, 

"parentType": "Purchase x0020 Credit x0020 Memo", 
"parentId": "de9f5d62-b421-ef11-9467-d62465a5064f", 
"lineNumber": 0, 


"documentFlowSales": false, 

"documentFlowPurchase": false, 

"lastModifiedDateTime": "2024-06-04T13:30:48.1072", 

"attachmentContent@odata.mediaEditLink": "http://demo- 
23cu5:7048/BC/api/v2.0/companies (a9baaac8-9dfc-eel1-9f8c- 
6045bde98c0£) /documentAttachments (00bbc3a6-7622-ef11-9467- 
d62465a5064f) /attachmentContent", 

"attachmentContent@odata.mediaReadLink": "http://demo- 
23cu5:7048/BC/api/v2.0/companies (a9baaac8-9dfc-eel1-9f8c- 
6045bde98c0£) /documentAttachments (00bbc3a6-7622-ef11-9467- 
d62465a5064f) /attachmentContent" 
} 


When you PATCH to the /attachmentContent endpoint, you would use the Id of the 
attachment, and the body is the file itself. An example URI would be: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}}) /documentAttachments (4f186ed9-c198-edll-bff5- 
6045bd02a4b4) /attachmentContent 


On the PATCH request, you need to specify in the HEADERS that this should be 
Content-Type: application/octet-stream, and data should be sent as such. 


No response body will be given, only an HTTP Status of 204, “No Content”. 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /documentAttachments (00bbc3a6-7622-ef11-9467-d62465a5064f£) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content”. You are not required to delete the content separately. 


CRUD Steps 


CREATING 


The most comment way of creating a document attachment is to use the Attachment 
FactBox from any Business Central document: 


CRONUS International Ltd. Sales Purchasing Inventory Posted Documents Shopify All Reports 


Posted Purchase Credit Memos: All v 2 B Í] Delete Home Print/Send v Credit Memo More options 


Buy-from Amount Including 
Vendor No. Buy-from Vendor Name Currency Code Due Date Amount VAT 


9 " = 
ount Psi "m 
1 Q1863656 American Wood Exports usp 21/01/2026 4,654.60 4,654.60 654. © Details | @ Attachments (0) 
30000 CoolWood Technologies 08/01/2026 28,344.00 35,430.00 -35,430.00 x 


Attachments 


Documents 


Notes + 


Then click on the number of documents on the right (in this case the 0). 


In the next page that opens, you can view any current attachments, or add one by using 
the "Attach File(s)...” link. 


Attached Documents 


yo, + New  & Edit List 


Attachment File Extension File Type Attached Date 


Attach File(s)... 


A new dialog box will open that will allow for a “drag and drop” of the file, or by clicking 
into the box, allow to upload the file from the filesystem. 
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Attached Documents 


yo) New &EditList {j Delete Download 


Attachment File Extension Attached Date 


— Attach File(s)... 


Attach a document. 


Drop a file here to upload, or 
click here to browse 


UPDATING 


The only field that is editable in the Attached Documents screen is the Attached Date. 
Modifying this field would trigger an update. 


DELETING 


To remove an attachment, select the line from the list and use the Delete Action in the 


Bound Actions 


No bound actions. 


No navigations. 


| Version Changes 


22.0 Added. 
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Chapter 69: Companies 


In Business Central, almost all data “belongs” to a specific company. This is why in the API 
you see that almost every call is underneath the company endpoint. 


This Endpoint is where you can get a list of the Companies in the BC system. 


Primary Key 


Name The name of the given Company. The field is 30 characters and 
alphanumeric. 


Field Map 


API JsoN: 


{ 
"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/$metadata#companies/Sentity”, 
"id": "559e3206-df3a-edll-bbae-6045bd8e554a^, 
"systemVersion": "21.0.46256.46853", 
"timestamp": 4284, 
"name": "My Company", 
NeasplayName™ 2 Sa, 
Dpusunessbscotfulendd: o 
YsystemereatedAt 2102/2 - 09 ESTNE OIN NT 
"systemCreatedBy": "00000000-0000-0000-0000-000000000001", 
NsvestemMocudieiedat P2299 STOI i 20m qa 
"systemModifiedBy": "00000000-0000-0000-0000-000000000001^ 


BUSINESS CENTRAL ENTITY: 
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Companies 


Ø Search New G&PEditList [ij Delete — &à Copy More options 


Enable 
Assisted 
Company 


Name name Display Name / Setup Setup Status 
->  CRONUS USA Inc. :  CRONUS USA Inc. E Completed 
My Company Completed 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies (559e3206-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a potentially longer list): 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadatafcompanies", 
pva lueta 
{ 
“id”: “86e811fb-de3a-ed11-bbae-6045bd8e554a”, 
“systemVersion  : yi 0md62506- 46/9594» 
“timestamp”: 4283, 
names DERONUST USAT Teny 
“daisplayName”: “7, 
"businessProfileId": "", 
""ewasEGuNCTseueexoUAEM S 92(72 (06) 52 900.8 2109)8 1.1.5 3 519254 7 
"systemCreatedBy": "00000000-0000-0000-0000-000000000001", 
"ewxenENmMexol IE EXoUNE V B “2022 OZ Sap. 8 285 iil a T SS n 
"systemModifiedBy": “00000000-0000-0000-0000-000000000001” 


"id": "559e3206-df3a-edll-bbae-6045bd8e554a", 
“NsystemVersion =; “210 4:62 510 46653: 4, 
“timestamp”: 4284, 
“name”: “My Company”, 
"displayName": "", 
"businessProfileId": 
ysystemereacedAt k M207 209-2 2 Ole 2 OP ae 
"systemCreatedBy": "00000000-0000-0000-0000-000000000001", 
SsystemModifuiedAt4: 92022-0/9-289m00]:298529729] 277 
"systemModifiedBy": "00000000-0000-0000-0000-000000000001" 


wi 
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CRUD Steps 


Due to the nature of how much performance-impact altering Companies can have on a 
Business Central system, it is inadviseable to make changes here without consulting a 
professional in a production environment. 


If you still need to do these steps, it is as simple as editing the Company List to change 
or delete companies. Depending on whether you are On-Premises or SaaS, you may need to 
use the New Company wizard to create companies, which is beyond the scope of this book. 


Bound Actions 


No bound actions. 


For clarity, almost all endpoints are a Navigation for the Companies endpoint, but they 
are included here for completeness. 


e items (page 323) 

e unitsOfMeasure (page 471) 

e picture (page 453) 

e defaultDimensions (page 417) 

e itemVariants (page 339) 

e customers (page 110) 

e customerFinancialDetails (page 123) 
e agedAccountsReceivables (page 93) 
e contactsInformation (page 105) 

e contacts (page 97) 

e vendors (page 291) 

e agedAccountsPayables (page 228) 
e companylnformation (page 398) 

e salesInvoices (page 168) 

e salesInvoiceLines (page 178) 

e dimensionSetLines (page 427) 

e pdfDocument (page 450) 

e attachments (page 378) 

e customerPaymentJournals (page 126) 
e customerPayments (page 132) 

e accounts (page 38) 

e taxGroups (page 466) 

e journals (page 70) 

e journalLines (page 76) 
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e employees (page 358) 

e timeRegistrationEntries (page 370) 
e generalLedgerEntries (page 59) 

e currencies (page 407) 

e paymentMethods (page 440) 

e dimensions (page 424) 

e dimensionValues (page 433) 

e paymentTerms (page 445) 

e shipmentMethods (page 457) 

e itemCategories (page 331) 

e cashFlowStatements (page 55) 

e countriesRegions (page 402) 

e salesOrders (page 184) 

e salesOrderLines (page 195) 

e retainedEarningsStatements (page 84) 
e balanceSheets (page 45) 

e trialBalances (page 88) 

e incomeStatements (page 66) 

e taxAreas (page 461) 

e salesQuotes (page 202) 

e salesQuoteLines (page 212) 

e salesCreditMemos (page 152) 

e salesCreditMemosLines (page 161) 
e purchaselnvoices (page 252) 

e purchaselnvoiceLines (page 261) 

e projects (page 365) 

e bankAccounts (page 50) 

e vendorPayments (page 298) 

e applyVendorEntries (page 231) 

e vendorPaymentJournals (page 303) 
e salesShipments (page 219) 

e salesShipmentLines (page 224) 

e purchaseReceipts (page 283) 

e purchaseReceiptLines (page 288) 

e purchaseOrders (page 267) 

e purchaseOrderLines (page 276) 

e customerSales (page 143) 

e vendorPurchases (page 308) 


No notable changes. 
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Chapter 70: Company Information 


For each company in Business Central, general information is collected in a single location 
for use throughout the system, such as address information to display on invoices. 


Primary Key 


Primary Key System identifier connecting the Company Information to the correct 
Company. The field is 10 characters and alphanumeric. 


Field Map 


API JSON: 


{ 


"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /companyInformation/Sentity”, 

"Qodata.etag": "W/N"JzE4OzIOMDI10TY30TA4MjQ2NjkyNDE7MDA7Jw--N"" , 

"id": "5a973all-df3a-edll-bbae-6045bd8e554a", 

“NdisplayName”: “CRONUS USA, Une. 

"addressLinel": "7122 South Ashford Street", 

"addressLine2": "Westminster", 

Neste” a. Acia ai p 

Sgiate”a NGA”, 

Deountr y US 47 

2poscal Code a Ro n2 

"phoneNumber": “+1 425 555 0100”, 

Sre Numos o. Si A25 555 OIL. 

Vema IKEDA 

“website”: 

“taxRegistrationNumber”: 

Neumnency€ode USD 

NcursentriccalVedrStarteDake’:. 7029-002 

Dir eliutsiteuoyo (d 4 

"experience": "Premium", 

SilastModtiiedbDateiime Ga: 02:2 PST ON ESTE REID A 

"pictureGodata.mediaReadLink": "https://api.businesscentral.dynamics.com/v2.0 
/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}}) /companyInformation(5a973a 
11-df3a-edl1-bbae-6045bd8e554a) /picture” 


) 
AMI 
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wi 


wi 


BUSINESS CENTRAL ENTITY: 


Company Information 


Related 
General Show less 


Name displayName Contact Name Adam Matteson 


Address addressLinel Phone No. 


Address 2 addressLine2 Federal ID No. 


P 


n 
ct 


City EORI Number 
State state Industrial Classification 


ZIP Code postalCode Picture TP 
E LJ 


cronus- 


SAT ZIP Code 


Country/Region Code 


Communication 


Phone No. phoneNumber IC Partner Code 
Fax No. faxNumber IC Inbox Type Database 
Email email IC Inbox Details 


Home Page website Open new Intercompany Setup page 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /companyInformation 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /companyInformation (5a973all-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (1 entity shown): 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies (( (companyID])) /companyInformation", 
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“value”: [ 


"Qodata.etag": "W/N"JzE4OzIOMDI1OTY3OTA4MjQ2NjkyNDE7MDA7Jw--V "" , 

"id": "5?973all-df3a-edll-bbae-6045bd8e554a", 

"displayName": "CRONUS USA, Inc.”, 

"addressLinel": "7122 South Ashford Street", 

"addressLine2": "Westminster", 

De ey 3. "eben 

MeueeuEs uen 

Deountr ye UIS 

Dpostalcodern MON" 

"phoneNumber": “+1 425 555 0100”, 

Meee Nl AS) "Si Mal oil’, 

Demani D 

“website”: Y, 

“taxRegistrationNumber”: 

“currencyCode”: “USD”, 

veurrentiisecal years carc Daren F202 OO 

Pavel: a SM 

"experience": "Premium", 

MiaseModmivedDacvelame 4: 2022 —09—2 295] 9:99] 5: 9/5 9/919 aie, 

"picture odata.mediaReadLink": "https://api.businesscentral.dynamics. 
com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies({{companyID}}) /companyInformatio 
n(5a973al1-df3a-ed11-bbae-6045bd8e554a) /picture” 

} 


wi 


] 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/companyInformation (5a973all-df3a-edll-bbae-6045bd8e554a) 


Example PATCH Request Body: 


"displayName": "SBI Sandbox", 
"phoneNumber": "0666-878-6666", 
"faxNumber": "0666-454-6660", 
"email": “noreply@sparebrained.com”, 
"website": "sparebrained.com" 


Example PATCH Response: 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /companyInformation/Sentity”, 
"Qodata.etag": “W/\”JzIwOzE2MTc4Nzg5MjUyOTMINTE3NjJEIMTswMDsn\"”, 
"id": “5a973all-df3a-ed1ll1-bbae-6045bd8e554a”, 
"displayName": “SBI Sandbox”, 
"addressLinel": "7122 South Ashford Street", 
"addressLine2": "Westminster", 
reus “atic emee 
Msitawe A: SGA, 
eons MUS S 
Dpostalcoden NOT am 
"phoneNumber": "0666-878-6666", 
"faxNumber": "0666-454-6660", 
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"email": “noreply@sparebrained.com”, 
"website": "sparebrained.com", 
"taxRegistrationNumber": "" 

Neumnency Code i= USD 
Seurrencihiocal Years cartare 43 2022 — Oil Oo" 


xim elus C 
"experience": "Premium", 
Mtas tMocdusturesatemes: v0: 0E] EOTS 


"pictureGodata.mediaReadLink": "https://api.businesscentral.dynamics.com/v2.0 
/{{tenantID}}/APIBook/api/v2.0/companies ({{companyID}}) /companyInformation (5a973a 
11-df3a-ed11-bbae-6045bd8e554a) /picture” 

} 


CRUD Steps 


CREATING 


The Company Information record is created automatically on creation of the company. 


UPDATING 


An easy update would be to alter the Address field. 


DELETING 


You cannot (or should not) delete the Company Information. 


Bound Actions 


No bound actions. 


e countryRegion (page 402) 


| Version Changes 


18.1 Some small changes in handling the Tax Registration Number. 
25.0 Added Experience field 
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Chapter 71: Countries/Regions 


This endpoint exposes some of the fields of one of the setup tables of the system, 
Countries/Regions. 


Primary Key 


Code The identifier for the given Country/Region. The field is 10 characters 
and alphanumeric. 


Field Map 


API JSON: 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({ {companyID}}) /countriesRegions/Sentity”, 
"Qodata.etag": "W/N"JzES5OzQ2NDCzNzEyOTUzNjIyMTg0MjkxOzAwOyc-^N"", 
"id": "bd14971e-df3a-ed11-bbae-6045bd8e554a", 
codo AT 
"displayName": "United Arab Emirates", 
vaddresskormat < Greve ESEPS Se x00 20r dc 
"lastModifiedDateTime": “2022-09-23T01:29:39.662” 


BUSINESS CENTRAL ENTITY: 
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Countries/Regions 


ly Delete 


Name 
United Arab Emirates City+ZIP C... After Com... 


Austna Blank Line... After Com... 
Australia City+State... After Com... 


Belgium ZIP Code+... After Com... 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /countriesRegions 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /countriesRegions (bd14971e-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


1 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /countriesRegions”, 
“value”: [ 
{ 
“@odata.etag”: “W/\"”JzE50zQ2NDczNzEyOTUZNjIyMTg0MjkxOzAwOyc=\"", 
"id": "bd14971e-df3a-edll-bbae-6045bd8e554a", 
“code”: “AR”, 
"displayName": “United Arab Emirates”, 
"addressFormat": “City x002B Post x0020 Code”, 
WihasiMediivedDatelime”:) Y 2022-09-23 0ik 2 Ol 9/95 6/67) 0 


“@odata.etag”: "W/N"JzESOzQ2NDYxNjk5NzA3NjkzMjU2NzAxOzAwOyc-V"" , 
"id": "bel4971e-df3a-edll-bbae-6045bd8e554a", 

Meode VATA, 

"displayName": "Austria", 

"addressFormat": "Blank x0020 Line x002B Post x0020 Code x002B City", 
SlastModtitedbDaceilaime a 20/2 9922 5 ON 2/9 S Se Guan 


"Qodata.etag": "W/N"JzE5OzO2NDY2MTIOMdgyNjk1NDgyOTYxOzAwOyc-N"", 
"id": "bf14971e-df3a-edll-bbae-6045bd8e554a", 

“coder VAU 

"displayName": "Australia", 

"addressFormat": "City x002B County x002B Post x0020 Code", 
»abevsngititeyelitiestiereliDie were ibus ma e027 OO 2 oni Omer SIS 19:0 TA 


), 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /countriesRegions 


Example POST Request Body: 


Meoqdece- SNAS 
“displayName”: “Narnia”, 
"addressFormat": “Blank x0020 Line x002B Post x0020 Code x002B City” 


Example POST Response: 


{ 
"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/countriesRegions/Sentity”, 
"Qodata.etag": WW/N"JzE5OzQ2MTI3ODU2NjUOOTQwMjg2MDQxOzAwOyc-V "" , 
"id": “8b315c75-0056-ed11-8c36-000d3a8dced5”, 
Neode: m NAT 
"displayName": "Narnia", 
"addressFormat": "Blank x0020 Line x002B Post x0020 Code x002B City", 
Dole castae loa: med 202 XO Arles ISO PEE 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/countriesRegions (80315c75-0056-ed11-8c36-000d3a8dced5) 


Example PATCH Request Body: 


“eode”: DADA 
“displayName”: “Andromeda” 


Example PATCH Response: 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/countriesRegions/Sentity”, 
"Qodata.etag": “W/\”JzE50zQ2MTI2NzgxMzYzMzUINzIyMjJMxOzAwOyc=\"", 
"id": “8b315c75-0056-ed11-8c36-000d3a8dced5”, 
Beodod- m SND, 
"displayName": "Andromeda", 
"addressFormat": "Blank x0020 Line x002B Post x0020 Code x002B City", 
“lastModifiedDateTime”: "2022-10-27T714:06:36.2072" 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /countriesRegions (80315c75-0056-ed11-8c36-000d3a8dced5) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


The Countries/Regions list is editable, so simply add a new entry to this list. 


Countries/Regions v Saved 


PY Search + New  BxEditList [ij] Delete EE Custom Address Format More options 


Contact 
ISO Numeric Address Address 
Name Code Format Format 


United Arab Emirates City+ZIP C... After Com... 
Austria Blank Line... After Com... 
Australia City+State... After Com... 


Belgium ZIP Code+... After Com... 


UPDATING 


Alter a field in an existing entry in the list, such as the Name field. 


DELETING 


Delete a record as normal. It may not allow you to do so if the Country/Region is in use, 
so test deletion by creating a new record for the express purpose of removal after. 


Bound Actions 


No bound actions. 
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No navigations. 


No notable changes. 
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Chapter 72: Currencies 


This endpoint exposes the setup table, Currencies. While it provides some fields about 
the setup, note that it does not expose any ability to fetch or update rate information. 


Primary Key 


Code The code used to identify the currency. The field is 10 characters and 
alphanumeric, however typically this code follows international 
standards and the three character value is used. 


Field Map 


API JsoN: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/currencies/Sentity”, 
"Qodata.etag": "W/N"JzIwOzEONzgONTIIMzES5MzMzNDQONTUOMTswMDsnV"", 

"id": "8514971e-df3a-ed11-bbae-6045bd8e554a", 
Neelys: EMNET 

"displayName": "Mexican peso”, 

Sevno p NEA. 

"amountDecimalPlaces": “2:2”, 
"amountRoundingPrecision": 0.01, 

Mila stMeodiivedDatelame4: | 2022-99-99 md0J 2/9/9919 Maz 


BUSINESS CENTRAL ENTITY: 
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+New [i Delete REditList Process ^ Exchange Rate Service v 


ISO Numeric Exchange Rate EMU Ri 

ISO Code Code Symbol Date Exchange Rate Curr.. A 

EUR Euro EUR 978 € 1/1/2020 0.9952 5 4 
MXN Mexican peso MXN 484 $ 1/1/2020 0.111114 4 


‘List. Process ^ Exchange Rate Service v 


Amount Amount Invoice Invoice 
Unrealized Unrealized Rounding Decimal Rounding Rounding 
Gains Acc. Losses Acc. Precision Places Precision Type 
0.01 2:2 0.01 Nearest 
001 2:2 0.01 Nearest 
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Currency Card 


CAD 


Report 


Home 


Navigate 


More options 


£7 Change Payment Tolerance 


General 


Code 

Description 

ISO Code 

ISO Numeric Code 
Symbol 

Unrealized Gains Acc. 


Realized Gains Acc. 


Rounding 


Invoice Rounding Pre... 


Invoice Rounding Type 


Amount Rounding Pr... 


Amount Decimal Plac... 


Unit-Amount Roundi... 


Unit-Amount Decima... 


GET 


amountRoundingPrecision 
Nearest 
0.01 


amountDecimalPlaces 


0.001 


Example GET Request URI List: 


Unrealized Losses Acc. 


Realized Losses Acc. 
EMU Currency 

Last Date Modified 
Last Date Adjusted 


Payment Tolerance 96 


Max. Payment Tolera... 


Appin. Rounding Pre... 
Conv. $ Rndg. Debit ... 
Conv. $ Rndg. Credit ... 


Max. Tax Difference A... 


Tax Rounding Type 


9/23/2022 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]])/currencies 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/currencies (8514971e-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 
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“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/currencies”, 
“value”: [ 


{ 


"Qodata.etag": "W/N"JzIwOzE2NjES5MzM3MTcC3MjIyMjQlOdkyMTswMDsnV"", 
"id": "8314971e-df3a-edll-bbae-6045bd8e554a^, 

eode ONDE 

"displayName": "Canadian dollar", 

Wenge NE. 

"amountDecimalPlaces": “2:2”, 

"amountRoundingPrecision": 0.01, 

alias eMocisturesibatsedumexd: 22/0/25: 09-26) Ome ols Oe esa 


"Qodata.etag": "W/N"JzIwOzE3MjMIMzExOTMxNzU3MzcxNTY1MTswMDsn'N"", 
"id": "8414971e-df3a-edll-bbae-6045bd8e554a", 

« code » : « EUR », 

« displayName » : « Euro », 

«c madsouL 5 5 ue xv 

MamountDbecimadPlaces4: “227, 

"amountRoundingPrecision": 0.01, 

“lastModi fiedDateTime”: 2022-09-23T01:291399:7127]77 


"Qodata.etag": “W/\”JzIwOzEONzgONTI1MzZE5MzMzNDQONTUOMTswMDsn\"”, 
"id": "8514971e-df3a-edll-bbae-6045bd8e554a", 

“code”: "MXN", 

"displayName": "Mexican peso", 

Vewnudoslés "S. 

"amountDecimalPlaces": "2:2^", 

"amountRoundingPrecision": 0.01, 

“lastModifiedDateTime”: "2022-09-23T01:29:39.1272" 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]])/currencies 


Example POST Request Body: 


Xcode: “CRED”, 
"DisplayName": "Republic Dataries" 


Example POST Response: 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/currencies/Sentity”, 
"Qodata.etag": "W/N"JzIwOzElOTMzODYyNDkxODQ3MzcONTExMTswMDsn'N"", 
"id": "addbc8d7-0056-ed11-8c36-000d3a8dced5", 
Meodere-a VERE DIC, 
"displayName": "Republic Dataries”, 
Sedo Sa 
"amountDecimalPlaces": “2:2”, 
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"amountRoundingPrecision": 0.01, 
"lastModifiedDateTime": “2022-10-27T14:08:34.9232” 


} 
PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /currencies (addbc8d7-0056-ed11-8c36-000d3a8dced5) 


Example PATCH Request Body: 


Biss ola NE p 
"amountDecimalPlaces": "2:5", 
"amountRoundingPrecision": 0.1 


Example PATCH Response: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/currencies/Sentity”, 
"Qodata.etag": “W/\”JzIwOzELOTMzODY yMZExNTM30DQ1MzZAwMTswMDsn\"”, 

"id": “addbc8d7-0056-ed11-8c36-000d3a8dced5”, 
“eerie m ERAT 

"displayName": "Republic Dataries", 

"symbol": "li^, 

"amountDecimalPlaces": "2:5", 
"amountRoundingPrecision": 0.1, 
“lastModifiedDateTime”: "2022-10-27T14:13:08.2532" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)))/currencies (addbc8d7-0056-ed11-8c36-000d3a8dced5) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


The Currencies list is editable. So, simply create a new entry in the list: 
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Currencies 


earc ew ¢ Edit List il] Delete it o" View rocess change Rate Service 
J9 Search +N B? Edit Li fii] Del Ê Ed Ovi P Exchange Rate S 


ISO Numeric Exchange Rate 
Description ISO Code Code Date Exchange Rate 


United Arab Emi... AED 784 1/1/2020 0.233753 
Australian dollar | AUD 1/1/2020 0.342995 
Bulgarian leva BGN 1/1/2020 0.316096 
Brunei Darussal... BND 1/1/2020 0.392997 
Brazilian real BRL 1/1/2020 0.245198 
Canadian dollar CAD 1/1/2020 0.431903 


UPDATING 


Alter an existing Currency in the list, such as the Description field. 


DELETING 


While you generally should not delete a currency if it is in use, you can test deletion by 
creating a new Currency for the purpose of deletion. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


No notable changes. 
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Chapter 73: Currency Exchange Rates 


Currency Exchange Rates lists the rates used in Business Central for Multicurrency 
transactions. 


Primary Key 


Currency Code The code used to identify the currency. The field is 10 characters and 
alphanumeric, however typically this code follows international 
standards and the three character value is used. 
Starting Date The start date when this rate was put into effect. 


Field Map 


API JSON: 
{ 
"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}}/currencyExchangeRates", 
Unies T 
{ 
"@odata.etag": "W/N"JzE5OzMxNDIzMzMwOTIzOTCc5NjYzMjAxOzAwOyc-N"", 
"id": "493eccee-9dfc-eell1-9f8c-6045bde98cOf", 
"currencyCode": "CAD", 
WisiceuciciineiDelee ts 01219 (OE Qf Wr 
"exchangeRateAmount": 100, 
"relationalCurrencyCode": "", 
"relationalExchangeRateAmount": 66.5604, 
"lastModifiedDateTime": "2024-04-17T09:36:58.3032" 


}, 


BUSINESS CENTRAL ENTITY: 
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Currency Exchange Rates - CAD 


Dp +New  BxEditlist [f] Delete 


Adjustment Relational Fix Exche 
Starting Currency Code Relational Exchange Rate Relational Exch. Exch. Rate Adjmt Exch ^ Rate 
Date 1 TY Currency Code Amount Rate Amount Amount Rate Amt Amount 


01/01/2024 | : ) 100.0 43.1903 100.0 43.1903 Curren 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies({{companyID}})/ currencyExchangeRates 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies({{companyID}})/ currencyExchangeRates (493eccee-9dfc-eel1-9f8c-6045bde98cO0f) 


Example GET Response (single): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({ {companyID}}/currencyExchangeRates/Sentity", 

"Qodata.etag": "W/N"JzE5OzMxNDIzMzMwOTIzOTC5NjYzMjAxOzAwOyc-N"", 

"id": "493eccee-9dfc-eell1-9f8c-6045bde98cO0f", 

"currencyCode": "CAD", 


Dotar ingDarte S 20922-1010). 
"exchangeRateAmount": 100, 
vrelationaleurrencycode Wn uun 
"relationalExchangeRateAmount": 66.5604, 
"lastModifiedDateTime": "2024-04-17T09:36:58.303Z" 


CRUD Steps 


CREATING 
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To create a new exchange rate, open the currency page (see previous endpoint) and click 
on the exchange rate: 


Brunei Darussal... 01/01/2024 0.392997 


Brazilian real 01/01/2024 0.245198 


Canadian dollar 01/01/2024 0.431903 


Swiss franc 01/01/2024 0.543424 
Czech koruna 01/01/2024 0.026618 


This will drill down into the rates and allow for entry of another rate line. 


Currency Exchange Rates - CAD 


p + New Bx Edit List 


Starting Date 1 Currency Code t Y Relational Currency Code Exchange Rate Amount Relational Exch. Rate Amount Adjustme 
01/01/2024 CAD 100.0 43.1903 
SAR 0.0 0.0 


May 2024 
Mon Tue Wed Thu Sat Sun 
29 30 1 2 


6 7 8 9 


13 14 15 16 


[20] 21 22 23 


27 28 29 30 


Fill out the start date, and the Exchange rate fields to generate a new line. 


UPDATING 


For the Currency Exchange Rate, a new line is all that is required, editing the line should 
only be used if it was originally entered incorrectly. 


DELETING 


Deleting the rates is not recommended, as it can have an impact on the financial 
transactions. However, selecting the line and using the Delete action at the top of the page 
will remove an entered line. 


Bound Actions 


No bound actions. 


e «Helpful suggestion with page no.» 
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| Version Changes 


23.0 Added. 
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Chapter 74: Default Dimensions 


While explaining the design concepts and uses of Dimensions is beyond the scope of the 
book, Dimensions are akin to a categorization/tagging system for transactions, with lots of 
potential rules, defaults, and controls. They enable detailed analysis of transactions to help sift 
through huge piles of data. 


The Default Dimensions endpoint is how to access which dimension codes and values are 
set as ‘default’ on a master record, such as a Customer or Item. 


This means you filter on which Table you want the default dimensions for and get back a 
list of Codes and Values. 


tables, but this endpoint only supports a subset of those 
tables: Customer, Vendor, Item, and Employee. See Part 8: 
Chapter 91: API Bugs (page 517) for more details. 


eo Note: Default Dimensions can be set on a wide array of system 


Primary Key 


Table ID Integer Identifier, which relates to the unique id of which table in 
Business Central this is connected to. 

Dimension The Dimension to which this record belongs. The field is 20 characters 

Code and alphanumeric. 

No. The selected Dimension Value for this Dimension Code. The field is 20 


characters and alphanumeric. 


Field Map 


API JsoN: 
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"Qodata.etag": “W/\”JzE50zY5NjcyNjJM40TQONDkOMzMwMTQxOzAwOyc=\"", 
"id": "d95a2523-df3a-edll-bbae-6045bd8e554a", 

"parentType": "Customer", 

“parentId”: "6c15971e-df3a-edll-bbae-6045bd8e554a", 
"dimensionId": "68572523-df3a-edll-bbae-6045bd8e554a", 
"dimensionCode": "AREA", 

"dimensionValueId": "c15a2523-df3a-edll1-bbae-6045bd8e554a", 
"dimensionValueCode": “70”, 

"postingValidation": "Code x0020 Mandatory" 


BUSINESS CENTRAL ENTITY: 


Accessing the Default Dimension is done by going to the relevant entity, such as 
Customer, and selecting the Dimensions action. This will open the Default Dimensions list for 
that entity: 


Customer 10000 


Default Dimensioy” oY 


Dimension Code f Dimension Value Code Value Posting Allowec 


AREA 70 Code Mandatory 
CUSTOMERGROUP 
DEPARTMENT 


The parent fields are not visible on the page, but can be confirmed to be present on the 
Default Dimension via the Page Inspector: 
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Customer 10000 > Page Inspection x 


See information about the page, its different elements, 
Default Dimensions P Search -+ New E Edit List fij Delete E and the source behind the data it displays. 


Dimension Code Dimension Value 


Page 
Code Value Posting Allowed Values Filter 


p Default Dimensions (540, List) 
> AREA EM 70 Code Manda... 


CUSTOMERGR... Table 
DEPARTMENT Default Dimension (352) 


View table 


Table Fields Extensions Page Filters 


p 


Table ID (1, Integer, PK) 
18 
Base Application 


No. (2, Code[20], PK) 
10000 
Base Application 


This Default Dimension example is on the Customer table (18) and is connected to the 
Customer No. (10000). 


GET 


Example GET Request URI List, which you should filter on parentId, which will be the Id 
of the related entity, such as a Customer, as follows: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/defaultDimensions?$filter-parentId eq bc7ef4e9-9dfc-eell-9f8c- 
6045bde98c0f 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/defaultDimensions (8e3eccee-9dfc-eell-9f8c-6045bde98c0f) 


Example GET Response (2 entities shown from a longer list): 


uva ue s Jr 
{ 

"Qodata.etag": "W/\"JzE50zcONTc4MjQ50TU4MDOZMTkyNzExOzAwOyc=\"", 
"id": "8e3eccee-9dfc-ee11-9f8c-6045bde98c0f", 
"parentType": "Customer", 
"parentId": "bc7ef4e9-9dfc-eell-9f8c-6045bde98c0f", 
"dimensionId": "223bccee-9dfc-eel1-9f8c-6045bde98cOf", 
"dimensionCode": "AREA", 
"dimensionValueId": "763eccee-9dfc-ee11-9f8c-6045bde98cOf", 
"dimensionValueCode": "70", 
"postingValidation": "Code x0020 Mandatory", 
"lastModifiedDateTime": "2024-04-17T09:36:58.852" 


"Qodata.etag": "W/N"JzE5Ozc5OTExMzMyNjO4MzcyMzYwMTAxOzAwOyc-N"", 
"id": "8f3eccee-9dfc-eell-9f8c-6045bde98cO0f", 
"parentType": "Customer", 
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"parentId": "bc7ef4e9-9dfc-eell-9f8c-6045bde98c0f", 
"dimensionId": "243bccee-9dfc-eel1-9f8c-6045bde98c0f", 


"dimensionCode": "CUSTOMERGROUP", 

"dimensionValueId": "7e3eccee-9dfc-ee11-9f8c-6045bde98cOf", 
"dimensionValueCode": "SMALL", 

Moos qaam Mes M 

"lastModifiedDateTime": "2024-04-17T09:36:58.8632Z" 


rp 
POST 


Example POST Request URI : 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /defaultDimensions (d55a2523-df3a-edll-bbae-6045bd8e554a) 


Example POST Request Body : 


“parentId”: "6c15971e-df3a-edl1-bbae-6045bd8e554a", 
"dimensionId": "6e572523-df3a-ed11-bbae-6045bd8e554a", 
"dimensionValueId": "d25a2523-df3a-edl1l-bbae-6045bd8e554a" 


Example POST Response : 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/defaultDimensions/Sentity”, 

"Qodata.etag": “W/\”JzIwOzExNDYxMzk2NDY2MzMONzZM5MzE3MTswMDsn\"”, 

"id": “180290e6-0Oba0-ed11-9a8a-6045bd02aa7Ta”, 

“parentType”: “Customer”, 

“parentId”: “6c15971le-df3a-edl1l-bbae-6045bd8e554a”, 

"dimensionId": "6e572523-df3a-ed11-bbae-6045bd8e554a", 

"dimensionCode": "SALESPERSON", 

"dimensionValueId": "d25a2523-df3a-edll-bbae-6045bd8e554a", 

"dimensionValueCode": "JO", 

Srexoxsneusre/edbabeleneanerw/ d 9» sog 4, 

"lastModifiedDateTime": “2024-04-17T09:36:58.852” 


PATCH 


Example PATCH Request URI : 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/defaultDimensions (180290*6-0ba0-ed11-9a8a-6045bd02aa7a) 


Example PATCH Request Body: 


"postingValidation": "Code x0020 Mandatory" 
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Example PATCH Response: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/defaultDimensions/Sentity”, 

"Qodata.etag": “W/\”JzIwOzExNDYxMzk2NDY3MzIxNTIONDYZMTswMDsn\”"”, 

"id": "180290e6-0ba0-ed11-9a8a-6045bd02aa7a", 

"parentType": "Customer", 

“parentId”: "6c15971e-df3a-edll-bbae-6045bd8e554a", 

"dimensionId": "6e572523-df3a-ed11-bbae-6045bd8e554a", 

"dimensionCode": "SALESPERSON", 

"dimensionValueId": "d25a2523-df3a-edl1-bbae-6045bd8e554a", 


"dimensionValueCode": "JO", 
"postingValidation": "Code x0020 Mandatory", 
"lastModifiedDateTime": “2024-04-17T09:36:58.852” 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/defaultDimensions (180290e6-0ba0-ed11-9?8a-6045bd02aa7a) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


For creating a new Default Dimension, select a Customer as a test, and from the Customer 
Card (via the Customers list), locate the Dimensions action. This will open the list of Default 
Dimensions. 


For each Dimension Code, you may only have one Dimension Value selected in this list. 
So, add a new Dimension Code, then select a Dimension Value for it. 


In CRONUS, we could add a new default to Customer 10000 that it should always be 
tagged with the Dimension SALESPERSON with a value of JO by adding the Dimension Code 
SALESPERSON: 
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Customer 10000 


Default Dimensions | 2 Search -+New — BZEditlist [i] Delete 


Dimension Code f Dimension Value Code Value Posting 


AREA 70 Code Mandatory 
CUSTOMERGROUP 


DEPARTMENT 


S Lii] 


Code T Name Blocked 


CUSTOMERGROUP Customer Group 
DEPARTMENT Department 
PURCHASER Purchaser 
SALESCAMPAIGN Sales campaign 


Then selecting JO for the Dimension Value: 


Customer 10000 


Default Dimensions LQ Search d- New X BZEditlist [i] Delete 


Dimension Code f Dimension Value Code Value Posting Allowed Values Filter 
AREA Code Mandatory 
CUSTOMERGROUP 
DEPARTMENT 
> SALESPERSON 


UPDATING 


You can trigger an update of the Default Dimension by adjusting the Value Posting field. 


DELETING 
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Default Dimensions can be directly deleted. They are used as a template for new 
documents and transactions. As such, removal will have no effect on existing documents and 
transactions. 


Bound Actions 


No bound actions. 


e items (page 323) 

e accounts (page 38) 

e dimensions (page 424) 

e dimensionValues (page 433) 
e customers (page 110) 

e vendors (page 291) 

e employees (page 358) 


| Version Changes 


23.0 Added lastModifiedDateTime. 
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Chapter 75: Dimensions 


While explaining the design concepts and uses of Dimensions is beyond the scope of the 
book, Dimensions are akin to a categorization/tagging system for transactions, with lots of 
potential rules, defaults, and controls. They enable detailed analysis of transactions to help sift 
through huge piles of data. 


This endpoint represents the setup table Dimensions, which is the parent in the 
parent/child tagging of Dimension Code and Dimension Value. 


Primary Key 


Code The identifier of the Dimension. The field is 20 characters and 
alphanumeric. 


Field Map 


API JSON: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/dimensions/Sentity”, 

"Qodata.etag": “W/\”JzIwOzEONTM3MjQ5NDc2NtgzODcyMjk4MTswMDsn\"”, 

"id": "68572523-df3a-edll-bbae-6045bd8e554a", 

"code": "AREA", 

"displayName": "Area", 

"lastModifiedDateTime": “2022-09-23T01:29:46.6632” 


BUSINESS CENTRAL ENTITY: 
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Dimensions 


D Search + Ee Edit List lif Delete i More options 


Code f Code Caption 


AREA : Area Code 
BUSINESSGROUP Business Group Businessgroup Code 
CUSTOMERGROUP Customer Group Customergroup Code 
DEPARTMENT Department Department Code 
PURCHASER Purchaser Purchaser Code 
SALESCAMPAIGN Sales campaign Salescampaign Code 
SALESPERSON Salesperson Salesperson Code 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /dimensions 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /dimensions (68572523-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/dimensions”, 

“value”: [ 


{ 


"Qodata.etag": “W/\”JzIwOzEONTM3MjQ5NDc2NtgzODcyMjk4MTswMDsn\"”, 
"id": "68572523-df3a-edll-bbae-6045bd8e554a", 

"code": "AREA", 

"displayName": "Area", 

"lastModifiedDateTime": “2022-09-23T01:29:46.6632” 


“@odata.etag”: "W/N"JzIwOzEONTM3MjQ2Mzg4MjA1MjA20TQ1MTswMDsnV"" , 
"id": "69572523-df3a-edll-bbae-6045bd8e554a", 

“code”: "BUSINESSGROUP^, 

"displayName": "Business Group", 

"lastModifiedDateTime": “2022-09-23T01:29:46. 682” 
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"Qodata.etag": “W/\”JzIwOzEONTM3MjQOzNTAIMjJU4MzUINTU3MTswMDsn\"”, 
"id": "6?*572523-df3a-edll-bbae-6045bd8e554a", 
Scode MCUSDoMBERGEOUPOT 
"displayName": "Customer Group", 
"lastModifiedDateTime": “2022-09-23T01:29:46.682” 
), 


CRUD Steps 


CREATING 


The Dimensions list is editable. So, a new entry can be created directly in the list: 


Dimensions 


JO Search -- New — BZEditlist [i] Delete Dimension More options 


Code f Name Code Caption 

> AREA : Area Area Code 
BUSINESSGROUP Business Group Businessgroup Code 
CUSTOMERGROUP Customer Group Customergroup Code 
DEPARTMENT Department Department Code 
PURCHASER Purchaser Purchaser Code 
SALESCAMPAIGN Sales campaign Salescampaign Code 
SALESPERSON Salesperson Salesperson Code 


UPDATING 


Alter a field, such as the Description. 


DELETING 


While you generally should not delete a Dimension if it is in use, you can test deletion by 
creating a new entry for the purpose of deletion. 


Bound Actions 


No bound actions. 


e dimensionValues (page 433) 


Changes 
23.0 Added consolidationCode. 
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Chapter 76: Dimension Set Lines 


While explaining the design concepts and uses of Dimensions is beyond the scope of the 
book, Dimensions are akin to a categorization/tagging system for transactions, with lots of 
potential rules, defaults, and controls. They enable detailed analysis of transactions to help sift 
through huge piles of data. 


This endpoint represents a complex concept, which is the Dimension Set ID. This is a 
single integer index that is a unique combination of all the many possible Dimension Codes 
and Values. 


Despite the name, the main purpose of this endpoint is to be able to get back a list of the 
Dimension Codes and Dimension Values tied to a particular entry, such as a Sales or Purchase 
Order line. 


As such, it is mostly used as a Navigation element from other endpoints, such as this call: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/salesOrders (1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /dimensionSetLines 


This allows the API to return a useful list for the given entity. The full list of supported 


entities is: 

e Journal Line. e Purchase Invoice Line. e Sales Order Line. 

e General Ledger Entry. e Purchase Receipt. e Sales Credit Memo. 

e Time Registration Entry. e Purchase Receipt Line. e Sales Credit Memo Line. 
e Purchase Order. e Sales Quote. e Sales Invoice. 

e Purchase Order Line. e Sales Quote Line. e Sales Invoice Line. 

e Purchase Invoice. e Sales Order. e Sales Shipment. 


e Sales Shipment Line. 


Primary Key 


Because each of the supported entities has only the Integer that is a mapping to the 
Dimension Set, which is a list of Dimension Codes and Values, there is no exact table behind 
this information. It is generated from the Dimension Set ID when needed, creating a list of 
Codes and Values through a Buffer (temporary) table called Dimension Set Entry. This table has 
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a Primary Key for the minimum required unique values, the Dimension Set ID and the 
Dimension Code. 


Field Map 


API JsoN: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({ {companyID}})/salesOrders (1e1219ad-1455- 
ed11-8c36-000d3a8dc661) /dimensionSetLines/Sentity”, 

"Qodata.etag^": "W/N"JzESOzMOMTAONzUwMjM2NDISNDASMTIxOzAwOyc-V"", 

"id": "68572523-df3a-ed11-bbae-6045bd8e554a", 

"code": "AREA", 

Mpamenu:ndz: ied 9a 55e 8e906-00/06d939«sdc06/17 

Yperen ^s Vocales M020 Order; 

“displayName”: “Area”, 

"valueId": "c15a2523-df3a-edl1-bbae-6045bd8e554a", 

"valueCode": "70", 

"valueDisplayName": "America North" 


BUSINESS CENTRAL ENTITY: 


This is found via the Dimensions action from the list involved. For the above example, 
that would be the Dimensions from the Sales Order: 


Edit - Order S-ORD101006 - Edit Dimension Set Entries 


YL Search -- New EPEditList [i] Delete 


Dimension Code t Dimension Value Code Dimension Value Name 
AREA 70 America North 
BUSINESSGROUP OFFICE Office 
CUSTOMERGROUP MEDIUM Medium Business 
DEPARTMENT SALES Sales 
SALESPERSON : JO Jim Olive 


This is a combination set of results, so: 


e code and displayName both come from the Dimension Code (the Dimensions 
endpoint). 

e valueCode and valueDisplayName both come from the Dimension Value 
Code (the Dimension Values endpoint). 
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GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrders(1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /dimensionSetLines 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrders(1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /dimensionSetLines (68572523-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/salesOrders (1e1219ad-1455- 
edi1-8c36-000d3a8dc661) /dimensionSetLines”, 

“value”: [ 

{ 
"Qodata.etag": "W/N"JzESOzMOMTAONzUwMjM2NDIS5NDASMTIxOzAwOyc-V"" , 
"id": "68572523-df3a-edll-bbae-6045bd8e554a", 
"code": "AREA", 
"parentId": "1e1219ad-1455-ed11-8c36-0004d3a8dc661", 
Sognene s Meeles xOO20 Orein; 
“displayName”: “Area”, 
"valueId": "c15a2523-df3a-edll-bbae-6045bd8e554a", 
myaduecodem: 0/2 
"valueDisplayName": "America North" 


"Qodata.etag": "W/N"JzIwOzEyNTAyNzMzOTA2MDIOOTOxNjglMTswMDsn'N"", 
"id": "6*572523-df3a-edll-bbae-6045bd8e554a", 

eodcm CUSTROMBERSEOUEPA 

"parentId": "1el1219ad-1455-ed11-8c36-000d3a8dc661", 
"rernaemupibyaere g "Sedis 0020 Orden, 

"displayName": “Customer Group”, 

"valueId": "c85a2523-df3a-edll-bbae-6045bd8e554a", 

"valueCode": "MEDIUM", 

"valueDisplayName": "Medium Business" 


"Qodata.etag": "W/N"JzESOzUzMTESMTIOOdk3NDYA4NTMyOTExOzAwOyc-V"" , 
"id": "65572523-df3a-edll-bbae-6045bd8e554a", 

"code": "DEPARTMENT^, 

"parentId": "1e1219ad-1455-ed11-8c36-000d3a8dc661", 
"yeenssumcabvas e s "Sedis x02) Greb, 

"displayName": "Department", 

"valueId": "cc5a2523-df3a-edll-bbae-6045bd8e554a", 

"valueCode": "SALES", 

"valueDisplayName": "Sales" 


), 


POST 


Example POST Request URI: 
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https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/salesOrders (1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /dimensionSetLines 


Example POST Request Body: 


“code”: “SALESPERSON”, 
SvalucCode d ITA 


Example POST Response: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesOrders (1e1219ad-1455- 
ed11-8c36-000d3a8dc661) /dimensionSetLines/Sentity”, 

"Qodata.etag": "W/N"JzESOzg2MTMAMDU2MDI 1MDEWMDgyNTcxOzAwOyc=\"", 

"id": "6e572523-df3a-edll-bbae-6045bd8e554a^, 

Scode: “SALESPERSON”, 

"parentId": "1e1219ad-1455-ed11-8c36-000d3a8dc661", 

PieeseepmubaseUs Seules 0020 Orcera, 

"displayName": "Salesperson", 

"valueId": "d35a2523-df3a-edll-bbae-6045bd8e554a", 

"valueCode": "LT", 

"valueDisplayName": "Lina Townsend" 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrders(1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /dimensionSetLines (6e572523-df3a-ed11-bbae-6045bd8e554a) 


Example PATCH Request Body: 


"valueCode": "OF" 


Example PATCH Response: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesOrders (1e1219ad-1455- 
ed11-8c36-000d3a8dc661) /dimensionSetLines/Sentity”, 

"Qodata.etag": "W/N"JzESOzg2MTMAMDU3ODIxMzI1NDOQ4MTOxOzAwOyc- V", 

"id": "6e572523-df3a-ed11-bbae-6045bd8e554a", 

“Neode”: “SALESPERSON”, 

"parentId": "1e1219ad-1455-ed11-8c36-0004d3a8dc661", 

Wiereiacinc iyo g "Sedis «0020! Order”; 

"displayName": "Salesperson", 

"valueId": "d45a2523-df3a-edl1-bbae-6045bd8e554a", 

"valueCode": "OF", 

"valueDisplayName": "Otis Falls" 
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DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/salesOrders(1e1219ad-1455-ed11-8c36- 
000d3a8dc661) /dimensionSetLines (6e572523-df3a-ed11-bbae-6045bd8e554a) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


For any of the entity types listed above that are unposted, there will be a Dimensions 
action to open the list of Dimension Code and Dimension Values for that entry. For example, 
for a Sales Order, you can open the Dimensions and see the following list: 


Edit - Order S-ORD101006 - Edit Dimension Set Entries 


Ø Search -- New  BzEditlist [i] Delete 


Dimension Code f Dimension Value Code Dimension Value Name 
AREA 70 America North 
BUSINESSGROUP OFFICE Office 
CUSTOMERGROUP MEDIUM Medium Business 
DEPARIMENT : SALES Sales 


Simply select a new Dimension Code and new Dimension Value Code. 


UPDATING 


Via the Dimensions list, change a Dimension Value Code. 


DELETING 


In the Dimensions list, you can remove a line directly. 


Bound Actions 


No bound actions. 
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Because this endpoint is mostly used from a variety of other endpoints to expand details, 
it has navigation links to many of the following endpoints: 


e salesInvoices (page 168) 

e salesInvoicelines (page 178) 

e dimensions (page 424) 

e customerPayments (page 132) 

e journalLines (page 76) 

e timeRegistrationEntries (page 370) 
e generalLedgerEntries (page 59) 
e salesOrders (page 184) 

e salesOrderLines (page 195) 

e salesQuotes (page 202) 

e salesQuoteLines (page 212) 

e salesCreditMemos (page 152) 

e purchaselnvoices (page 252) 

e purchaselnvoiceLines (page 261) 
e vendorPayments (page 298) 

e salesShipments (page 219) 

e salesShipmentLines (page 224) 

e purchaseReceipts (page 283) 

e purchaseReceiptLines (page 288) 
e purchaseOrders (page 267) 

e purchaseOrderLines (page 276) 


| Version Changes 
More valid Parent Type Entities were added in this version: 
e Purchase Invoice. 


e Purchase Invoice Line. 


More valid Parent Type Entities were added in this version: 
e Purchase Order. 
e Purchase Order Line. 
More valid Parent Type Entities were added in this version: 
Sales Shipment. 
Sales Shipment Line. 
Purchase Receipt. 
Purchase Receipt Line. 
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Chapter 77: Dimension Value 


While explaining the design concepts and uses of Dimensions is beyond the scope of the 
book, Dimensions are akin to a categorization/tagging system for transactions, with lots of 
potential rules, defaults, and controls. They enable detailed analysis of transactions to help sift 
through huge piles of data. 


This endpoint represents the setup table Dimension Values, which is the child in the 
parent/child tagging of Dimension Code and Dimension Value. For each Dimension Code, you 
can have a separate list of Dimension Values. 


Primary Key 


Dimension The Dimension to which this record belongs. The field is 20 

Code characters and alphanumeric. 

Code The selected Dimension Value for this Dimension Code. The field is 
20 characters and alphanumeric. 


Field Map 


API JSON: 


{ 

"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /dimensionValues/Sentity”, 

"Qodata.etag": “W/\”JzE50zQ2NDgxNjk2NDY5MZA1IMzE3MzIxOzAwOyc=\"", 

"id": "b95a2523-df3a-ed11-bbae-6045bd8e554a", 

eode M 

"dimensionId": "68572523-df3a-ed11-bbae-6045bd8e554a", 

"displayName": "Europe", 

CilastModtitedbDatelime “4:3 2022-09-23 m9]88::2:91 5/5 (219 ra 


BUSINESS CENTRAL ENTITY: 


Accessing the Dimension Values for a given Dimension is via the Dimensions list, then 
selecting the Dimension Values action. 
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Dimensions S CUSTOMERGROUP - tomer Group 


p Search -+ Ne Dimension Va pt Search EZ Edit List ll] Delete 


Dimension 
Code Value Type 


| LARGE : Large Business Standard 


MEDIUM Medium Business Standard 
SMALL Small Business Standard 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/dimensionValues 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/dimensionValues (b95a2523-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


1 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/dimensionValues”, 
“valuen i 
{ 
"Qodata.etag": "W/N"JzES5OzQ2NDgxNjk2NDY5MzAlMzES3MzIxOzAwOyc-^N"", 
"id": "b95a2523-df3a-edl11-bbae-6045bd8e554a", 
eodem 
"dimensionId": "68572523-df3a-ed11-bbae-6045bd8e554a", 
"displayName": "Europe", 
wihasiMeodiivedbDatelame” 52022-0019 29) m0/ 8 42/9 5] 5 2] OP] 4 


"Qodata.etag": "W/N"JzE5OzQ2NDc4ODM3MTc5NjUyNTcC5OTExOzAwOyc-NV"", 
"id": "ba5a2523-df3a-edll-bbae-6045bd8e554a^", 

peodcu Y 20", 

"dimensionId": "68572523-df3a-edll-bbae-6045bd8e554a", 
"displayName": "Europe North", 

tascMocisturesiat:eiumed 027 90-2259 TONO I STO RIZ d 


“@odata.etag”: "W/N"JzE5OzQ2NDc1OTgwNTYOMzgxNjMONjQxOzAwOyc-'N"", 
"id": "bb5a2523-df3a-edll-bbae-6045bd8e554a", 

codec 

"dimensionId": "68572523-df3a-edll-bbae-6045bd8e554a", 
"displayName": "Europe North (EU)", 

SoabevsnEvteyolitiestere Deere sb s 8921012222 —(0]/9) 2: SITO dL 72$) 8:555) c Sila 


), 
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CRUD Steps 


CREATING 


The Dimension Values list is editable, so a new entry can be created directly in the list: 


Dimensions CUSTOMERGROUP - Customer Group 


Dimension Values | 2 Search + New EZ Edit List li] Delete More options 


Dimension 
Code Name Value Type Totaling 


| LARGE : Large Business Standard 


MEDIUM Medium Business Standard 


SMALL Small Business Standard 


UPDATING 


Alter a field, such as the Name. 


DELETING 


While you generally should not delete a Dimension Value if it is in use, you can test 
deletion by creating a new entry for the purpose of deletion. 


Bound Actions 


No bound actions. 


e dimensions (page 424) 


| Version Changes 


23.0 Added consolidationCode. 
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Chapter 78: Dispute Status 


Dispute Status is used in Posted Sales Invoices to provide a reason why an invoice was 


credited. 
Primary Key 
Code An alphanumeric 10 character field. 
Field Map 
API JSON: 
{ 
"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}})/disputeStatus", 
"value": [ 


{ 


"Qodata.etag": "W/\"JzZE50zY1IMDczOTk2MzEyNDU4NzZO4NTMxOzAwOyc=\"", 
"id": "e9272099-dd1l1-ef11-9f8b-6045bde9cc61", 

Wiexexolew gr — ap VIOYIECO TE v 

"displayName": "Duplicate invoice dispute arguments" 


"Qodata.etag": "W/\"JzE50zcyMzY yODUZMTIxMjJMINTULODQxOzAwOyc=\"", 
"id": "ea272099-dd1ll-ef11-9f8b-6045bde9cc61", 

"codcm PETS 

"displayName": "Disputed invoices relating to the price" 


"Qodata.etag": "W/N"JzE5OzEWMDcCOMDMxODC3NjMwMzQ1MjMxOzAwOyc-N"", 
"id": "eb272099-ddll-ef11-9f8b-6045bde9cc61", 

MerexolsM e MOO Pit T II TCU 

"displayName": "A disputed invoice due to quality" 


BUSINESS CENTRAL ENTITY: 
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€ Dispute Status | Work Date: 22/01/2026 v/ Saved 


ptu +New  BEEditlist [iJ Delete 


Overwrite on 
Code Description hold 


3 INVOICH : Duplicate invoice dispute arguments o 


PRICE Disputed invoices relating to the price M 


QUALITY A disputed invoice due to quality O 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID)]))/disputeStatus 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID]])/disputeStatus (e9272099-dd11-ef11-9f£85-6045bde9cc61) 


Example GET Response (single): 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}})/disputeStatus/Sentity", 

"@odata.etag": "W/\"JzE50zY1IMDczOTk2MzEyNDU4NzZO4NTMxOzAwOyc=\"", 

Wiel Way) ooi fa Suelo GOA ccelo 

Wrereyole es UII 

"displayName": "Duplicate invoice dispute arguments" 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID)]))/disputeStatus 


Example POST Request Body: 


eodem m SSH? Pic 7 
"displayName": "Issue with shipping.” 
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Example POST Response: 


{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/$metadata#tco 
mpanies ({{companyID}})/disputeStatus/Sentity", 

"Qodata.etag": "W/N"JzIWOzEzNjA4MTgONjMyNjc1ODAzNDIwMTswMDsnN"", 

"id": "ab008384-b816-ef11-9e61-fef8811a716e", 

codec t NU SHIPPING 

"displayName": "Issue with shipping." 


} 
PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies(((companyID)])/disputeStatus (ab008384-b816-ef11-9e61-fef8811a716e) 


Example PATCH Request Body: 


"displayName": "Issue with shipping services Late" 


Example PATCH Response: 


{ 

"Qodata.context": "https://api.businesscentral.dynamics.com/v2.0/Smetadata#co 
mpanies ({{companyID}})/disputeStatus/Sentity", 

"Qodata.etag": "W/N"JzIwOzE2MTUAMjk1MzAzMjOlOTYAMTAwMTswMDsnN"", 

"id": "ab008384-b816-ef11-9e61-fef8811a716e", 

codcm SENIEPIINGU, 

"displayName": "Issue with shipping services Late" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies({{companyID}})/ /dimensionSetLines (ab008384-b816-ef11-9e61-fef8811a7166e) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


To create a new status, simply open the Dispute Status page and add a new code and 
description on a new line. 
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€- Dispute Status | Work Date: 22/01/2026 v Saved 


[a] +New EEditList [a] Delete 


Overwrite on 
Code f Description hold 
INVOICE : Duplicate invoice dispute arguments 


PRICE Disputed invoices relating to the price 


QUALITY A disputed invoice due to quality 


UPDATING 


Updating the code field might trigger a rename in Business Central, and depending on 
the number of records to be updated, could take a significant amount of time. 


DELETING 


Deleting a record from this table is not recommended, since there is a chance of data loss 
in the Posted Sales Invoices. 


Bound Actions 


No bound actions. 


Navigation 


e «Helpful suggestion with page no.» 


History 


| Version Changes 


24.0 Added. 
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Chapter 79: Payment Method 


The Payment Method is noted on Customers and Vendors, as well as on Sales and 
Purchase Documents. This endpoint allows you to access the description of the Payment 
Method in use. 


Primary Key 


Code The identifier for the Payment Method. The field is 10 characters and 
alphanumeric. 


Field Map 


API JSON: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/$metadata#companies ({{companyID}})/paymentMethods/Sentity”, 

"Qodata.etag": "W/N"JzIwOzEONTM3MDAxNzcxMDUzMDQOODUwMTswMDsnV"", 

"id": "423fd9f6-e33a-edl1l-bbad-000d3a394afc", 

"code": “PAYPAL”, 

"displayName": "PayPal payment", 

"lastModifiedDateTime": “2022-09-23T02:03:53.9132” 


BUSINESS CENTRAL ENTITY: 
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Payment Methods 


New  & Edit A? Ñ Delete G$ Translation More options 


Pmt. Export 
Description pe N Line Definition 


Payment on account G/L Account 


Bank Transfer G/L Account 
BNKCONV... Bank Data Conversion for Dom... G/L Account 
BNKCONVI... Bank Data Conversion for Inter... G/L Account 


rann Card ansemant CA Arrest 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /paymentMethods 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/paymentMethods (423f£d9£6-e33a-ed11-bbad-000d3a394afc) 


Example GET Response (3 entities shown from a longer list): 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/paymentMethods”, 

“value”: | 


{ 


"Qodata.etag": "W/N"JzIwOzEONTM3MDAxNzcxMDUzMDQOODUwMTswMDsnV"", 
"id": "423fd9f6-e33a-edll-bbad-000d3a394afc^", 

code qM DAYS 

"displayName": "PayPal payment", 

»*lbevenEln(xs ab eatcxelibieu Eie rabn S. 9 2(0)2/2 (0/9) 52/9) 400)2: 8019) B 159) Sil sya 


"Qodata.etag": "W/N"JzIwOzEONTM3ODEyNTg3NDU3NDE3Otc5MTswMDsnN "" , 
"id": "e9562523-df3a-edll-bbae-6045bd8e554a", 

eode AC NI 

"displayName": "Payment on account", 

"lastModifiedDateTime": “2022-09-23T02:02:47.7632” 


“@odata.etag”: "W/N"JzIwOzEONTM3ODA1NTQyNTg4NDA3NDg2MTswMDsnV"" , 
"id": "ea562523-df3a-edll-bbae-6045bd8e554a^", 
"code": "BANK", 
"displayName": "Bank Transfer", 
"lastModifiedDateTime": "2022-09-23T02:02:47.782" 
), 


PART 7: VARIOUS 
CHAPTER 79: PAYMENT METHOD 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/paymentMethods 


Example POST Request Body: 


Decode: “REMN/, 
"displayName": "Rock Management" 


Example POST Response: 


1 

"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({{companyID}}) /paymentMethods/Sentity”, 

"Qodata.etag": “W/\”JzIwOzEONTM3MDAZNDY 3MDAxMjExMTgwMTswMDsn\"”, 

"id": "7fcdd0fb-be56-ed11-8c34-6045bda91864", 

"code": "RKMN", 

"displayName": "Rock Management", 

"lastModifiedDateTime": “2022-10-28T12:49:43.492” 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)]) /paymentMethods (7£cdd0fb-be56-ed11-8c34-6045bda91864) 


Example PATCH Request Body: 


"code": “ROCKMGMT” 


Example PATCH Response: 


{ 

"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies (( (companyID])) /paymentMethods/Sentity", 

"Qodata.etag": "W/N"JzIwOzEONTM3MDA1MzMxNTUZzMjkwMDYyMTswMDsn"V"", 

"id": "7fcdd0fb-be56-ed11-8c34-6045bda91864", 

Neode” i “ROCKMEML”, 

"displayName": "Rock Management”, 

pelasiMedaseurecbatelumed:qe02 NO POTNIT TRE X71 


DELETE 
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Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)]) /paymentMethods (7£cdd0fb-be56-ed11-8c34-6045bda91864) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 
The Payment Methods list is editable. So, simply create a new entry. 


Payment Methods v Saved 


Ø Search + New EZ Edit List f] Delete E$ Translation More options 


Direct Debit 
Bal. Account Bal. Account Direct Pmt. Terms Pmt. Export 
Code f Description Type No. Debit Code Line Definition 


ACCOUNT : Payment on account G/L Account n 


S80 


BANK Bank Transfer G/L Account 
BNKCONV... Bank Data Conversion for Do... | G/L Account BANKDATAC... 
BNKCONVI... Bank Data Conversion for Inte... G/L Account BANKDATAC... 
CARD Card payment G/L Account 
CASH Cash payment G/L Account 


Bau 00 


CHECK Check payment G/L Account 
GIRO Giro transfer G/L Account 
INTERCOM Intercompany payment G/L Account 


SOO 


MULTIPLE Multiple payment methods G/L Account 


S 


PAYPAL PayPal payment G/L Account 


UPDATING 


Alter a field, such as the Description. 


DELETING 


While you generally should not delete a Payment Method if it is in use, you can test 
deletion by creating a new entry for the purpose of deletion. 


Bound Actions 
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No bound actions. 


Navigations 


No navigations. 


No notables changes. 
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Chapter 80: Payment Terms 


The Payment Terms are noted on Customers and Vendors, as well as on Sales and 
Purchase Documents. This endpoint allows you to access the description of the Payment Term 
in use and some information about the dates and discounts. 


Primary Key 


Code The identifier for the Payment Term. The field is 10 characters and 
alphanumeric. 


Field Map 


API JsoN: 


{ 

"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/paymentTerms/Sentity”, 

"Qodata.etag": "W/N"JzE5Ozc5OTI1MjAzNjQ3OtcxNDk2MtcxOzAwOyc-N"", 

"id": "8014971e-df3a-ed11-bbae-6045bd8e554a", 

Scode es IAS 

“displayName”: “Net 7 days”, 

"dueDateCalculation": “7D”, 

Meuseounbbatecaulxculat omne 

"discountPercent": 0, 

"calculateDiscountOnCreditMemos": false, 

Doa sMedaeurecateTrugmeds: 022-9. 29 m) s Zoi 9195 027) 


BUSINESS CENTRAL ENTITY: 
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Payment Terms 


Ø Search 


Due Date Discount Date 


Calculation Ca'cuiation r Description 


Code 


10 DAYS : 10D Net 10 days 
14 DAYS 14D Net 14 days 
15 DAYS 15D Net 15 days 
1M(8D) 1M 2 1 Month/296 8 days 


7? mave an Mat 2 clever 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /paymentTerms 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /paymentTerms (8014971e-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (2 entities shown from a longer list): 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/paymentTerms”, 

“value”: [ 


{ 


"Qodata.etag": “W/\”JzE50zUzZODY40DI yMjg2MzOzNzQ4NDYxOzAwOyc=\"", 
"id": "7814971e-df3a-edll-bbae-6045bd8e554a", 

“code Sag DAYS”, 

"displayName": "Net 10 days", 

"dueDateCalculation": “10D”, 

"discountDateCalculation": "^", 

"discountPercent": O0, 

"calculateDiscountOnCreditMemos": false, 

wihasiMeodienediDatelaime” 2022-09-23 ]/]e 2 «9/5 IO FK E 


"Qodata.etag": "W/N"JzE5OzYyODczMDQ2Njg4MjczMDQ4MzYxOzAwOyc-^N"", 
"id": "7914971e-df3a-ed1ll-bbae-6045bd8e554a^, 

PMeode4 WII DAYS a 

"displayName": "Net 14 days", 

"dueDateCalculation": “14D”, 

Mduiseournmtbatecaxcul'atu ond 

"discountPercent": O0, 

"calculateDiscountOnCreditMemos": false, 

MiaistMeodtinlediDakelames m0: 99. 29 m) x2 INI MEOFK E 
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}, 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /paymentTerms 


Example POST Request Body: 


eode VAMi(daM)) 4, 

"displayName": "4 Months/2% 1 Month”, 
"dueDateCalculation": “4M”, 
Madusecountebatecabtceulatudon/^:s 0M 
"discountPercent": 20, 
"calculateDiscountOnCreditMemos": true 


Example POST Response: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/paymentTerms/Sentity”, 

"Qodata.etag": “W/\"JzE50zE4MTU4NzZEONDY 20TYwMjA1ODMxOzAwOyc=\"", 

"id": "f3607ec6-bf56-ed11-8c34-6045bda91864", 

Scode 4 VII)" 

"displayName": "4 Months/2% 1 Month”, 

"dueDateCalculation": “4M”, 

"discountDateCalculation": "1M", 

"discountPercent": 20, 

"calculateDiscountOnCreditMemos": true, 

"lastModifiedDateTime": “2022-10-28T12:55:24.7272” 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /paymentTerms (£3607ec6-bf56-ed11-8c34-6045bda91864) 


Example PATCH Request Body: 


eode MED 

"displayName": "3 Months/2% 15 Days”, 
"dueDateCalculation": "3M", 
NeisicountDakeCatculacilen -NSDI 
"discountPercent": 25, 
“calculateDiscountOnCreditMemos”: false 
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Example PATCH Response: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/paymentTerms/Sentity”, 

"Qodata.etag": “W/\”JzE50zE4MTU4NZEONDY20TYwMjA1ODMxOzAwOyc=\"", 

"id": "f3607ec6-bf56-ed11-8c34-6045bda91864", 

Neode 4 AMM 

"displayName": “4 Months/2% 1 Month”, 

"dueDateCalculation": “4M”, 

"discountDateCalculation": "1M", 

"discountPercent": 20, 

"calculateDiscountOnCreditMemos": true, 

"lastModifiedDateTime": "2022-10-28T12:55:24.7272Z" 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /paymentTerms (£3607ec6-b£56-ed11-8c34-6045bda91864) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 


The Payment Terms list is editable. So, simply create a new entry. 
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Payment Terms v Saved 


Ø Search New — BEEditList [i] Delete E$ Translation More options 


Calc. 
Pmt. 
Due Date Discount Date Disc. on 
Code f Calculation Calculation Discount% Cr. Description 


10 DAYS $ 10D 
14 DAYS 14D 
15 DAYS 15D 
1M(8D) 1M 
2 DAYS 2D 
21 DAYS 

30 DAYS 

60 DAYS 

7 DAYS 

CM 


Net 10 days 

Net 14 days 

Net 15 days 

1 Month/296 8 days 
Net 2 days 

Net 21 days 

Net 30 days 

Net 60 days 

Net 7 days 


Current Month 


oO o o o o o o N O O o 
0/0/0/0/0/0/0/0/0/0/0 


Cash on delivery 


UPDATING 


Alter a field, such as the Description. 


DELETING 


While you generally should not delete a Payment Term if it is in use, you can test deletion 
by creating a new entry for the purpose of deletion. 


Bound Actions 


No bound actions. 


No navigations. 


No notable changes. 
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Chapter 81: PDF Document 


This endpoint works somewhat similarly to the Attachments endpoint, in that you read a 
record associated with a parentType and parentld, and it responds with objects containing a 
mediaReadLink to access the content. 


However, this is a read-only endpoint designed to fetch the default document PDF for a 
variety of different document types. This is controlled by the Business Central Report engine, 
including Document layouts and such. The result should generally be the same result as going 
to the associated document and selecting the Print action. 


The valid types for this endpoint include: 


e Journal. 

e Sales Order. 

e Sales Quote. 

e Sales Credit Memo. 

e Sales invoice. 

e Purchase Invoice. 

e Purchase Order (as of 17.5). 


Primary Key 


Id The generated identifier for the PDF Document. The field is a GUID. It 
is locked and managed by BC. 


Field Map 


API JSON (SINGLE): 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesInvoices (5e7604f6-1155- 
ed11-8c36-000d3a8dc661) /pdfDocument/Sentity", 
“@odata.etag”: “W/\”JzIwOzE1Njk1NjQ4MTO3Nzc3NjM4NTAZMTswMDsn\"", 
Nid“ S5e7io04to-1155-eddil—siccio 000dsasdecoie, 
"parentId": "5e7604f6-1155-ed11-8c36-000d3a8dc661", 
Neeieaineiyyjoe 3 Seuliss) <OO20 MT One 
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“pdfDocumentContent@odata.mediaReadLink”: “https://api.businesscentral.dynami 
cs.com/v2.0/{{tenantID} }/APIBook/api/v2.0/companies ({ {companyID}}) /salesInvoices ( 
5e7604£6-1155-ed11-8c36-000d3a8dc661) /pd£Document/pdfDocumentContent" 

} 


Using GET against the /pdfDocumentContent provided will fetch the PDF file as an 
application/octet-stream that can be saved/processed. 


BUSINESS CENTRAL ENTITY: 


This will be the relevant report, which can vary significantly based on configurations. 


GET 


Example GET Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies((companyID)])/salesInvoices(5e7604f6-1155-ed11-8c36- 
000d3a8dc661) /pd£Document 


Example GET Response (1 entity shown): 


{ 


“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/salesInvoices (5e7604f6-1155- 
ed11-8c36-000d3a8dc661) /pdfDocument/Sentity”, 

"Qodata.etag": “W/\”JzE50zM2MDY0Mjg5NzZA5NjQ2MzU4MzQxOzAwOyc=\"", 

"id": "5e7604f6-1155-ed11-8c36-000d3a8dc661", 

"parentId": "5e7604f6-1155-ed11-8c36-0004d3a8dc661", 

Sparentuhy pew Aseas 0020 MS momo 

"pdfDocumentContentGodata.mediaReadLink": "https://api.businesscentral.dynami 
cs.com/v2.0/{{tenantID} }/APIBook/api/v2.0/companies ({ {companyID}}) /salesInvoices ( 
5e7604£6-1155-ed11-8c36-000d3a8dc661) /pdfDocument /pdfDocumentContent” 


} 
CRUD Steps 


This is a report access route, so any document or journal that meets the criteria will work 
for generating data for this endpoint. 


Bound Actions 


No bound actions. 


e salesInvoices (page 168) 
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e salesQuotes (page 202) 
e salesCreditMemos (page 152) 
e purchaselnvoices (page 252) 


History 
Version Changes 
17.5 Purchase Order added to the supported Document Types. 
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Chapter 82: Picture 


The picture endpoint is another specialized file content access path, similar to the 
Attachment system, in which one fetches a record based on parentType and parentId, and 
gets back a link to access or update the media of the record involved. 


This endpoint is also unusual in that you can GET, PATCH, and DELETE, but not POST. This 
is because the DELETE action only removes the Picture, not the related entity. All the related 
entities, to set a new Picture, are a PATCH call. 


Primary Key 


This Attachment endpoint is a buffer table that looks up and writes back information from 
multiple tables. 


Depending on the parentType filter, the parentId will be a GUID lookup to the 
systemld of any of: 


e Customer. 
e |tem. 

e Vendor. 

e Employee. 
e Contact. 


Field Map 


API JSON: 


{ 
"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/pictures”, 
Myelin a | 
{ 
“@odata.etag”: "W/N"JzIwOzE3NDUwMTY1IOTUzMjEyOTI3NzOzMTswMDsn'N"", 
"id": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 
"parentType": "Customer", 
Saelens OOF 
"height": 400, 
"contentType": “image/jpeg”, 
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"pictureContentGodata.mediaEditLink": "https://api.businesscentral.dy 
namics.com/v2.0/{{tenantID} }/APIBook/api/v2.0/companies ({ {companyID}}) /pictures (6 
c15971e-df3a-edll-bbae-6045bd8e554a)/pictureContent", 

"pictureContentGodata.mediaReadLink": "https://api.businesscentral.dy 
namics.com/v2.0/{{tenantID} }/APIBook/api/v2.0/companies ({ {companyID}}) /pictures (6 
c15971le-df3a-ed11-bbae-6045bd8e554a) /pictureContent” 

} 


] 


BUSINESS CENTRAL ENTITY: 


This varies according to which parentType is involved. The above represents the Picture 
of a Customer entity in CRONUS. 


GET 


Example GET Request using filtering: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/pictures?$filter=parentTyp q ‘Customer’ and id eq 6c15971e- 
df3a-edll1-bbae-6045bd8e554a 


Example GET Request using Navigation: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/customers(6c15971e-df3a-edll-bbae-6045bd8e554a)/picture 


Example GET Response (1 entity shown): 


{ 
"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/pictures”, 
“value”: [ 
{ 

"Qodata.etag": “W/\”JzIwOzE3NDUWMTY10OTUZMjJEyOTI3NzQzMTswMDsn\"”, 

"id": "6c15971e-df3a-ed11-bbae-6045bd8e554a", 

"parentType": "Customer", 

Syalehelats RT OT 

"height": 400, 

"contentType": "image/jpeg", 

"pictureContentGodata.mediaEditLink": "https://api.businesscentral.dy 
namics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/companies ({ {companyID}})/pictures (6 
c15971e-df3a-edl1-bbae-6045bd8e554a)/pictureContent", 

"pictureContentGodata.mediaReadLink": "https://api.businesscentral.dy 
namics.com/v2.0/{{tenantID} }/APIBook/api/v2.0/companies ({ {companyID}}) /pictures (6 
c15971e-df3a-edll-bbae-6045bd8e554a)/pictureContent^" 

} 


] 


You then get a mediaReadLink you can GET to receive an application/octet-stream 
containing the image data/file. 
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PATCH 


Typically, you would only use a PATCH call to set the Picture to the supplied image, via 
the /pictureContent path. 


On the PATCH request, you need to specify in the HEADERS that this should be Content- 
Type: application/octet-stream, and data should be sent as such. 


No response body will be given, only an HTTP Status of 204, “No Content”. 


DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /employees (lec3a841-df3a-ed11-bbae-6045bd8e554a) /picture 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 


On one of the related types, such as Items, import a Picture via the Picture FactBox. 


UPDATING 


The same process as Creating will work, as it replaces the existing picture. 


DELETING 


In the Picture factbox, there is an option to Delete the picture of the entity. 


Bound Actions 


No bound actions. 


e items (page 323) 
e customers (page 110) 
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e contacts (page 97) 
e vendors (page 291) 
e employees (page 358) 


History 
Version Changes 
18.0 Contacts added. 
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Chapter 83: Shipment Methods 


The Shipment Method is noted on Customers and Vendors, as well as on Sales and 
Purchase Documents. This endpoint allows you to access the description of the Shipment 
Method in use. 


Primary Key 


Code The identifier for the Shipment Method. The field is 10 characters and 
alphanumeric. 


Field Map 


API JsoN: 


{ 

"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/shipmentMethods/Sentity”, 

"Qodata.etag": “W/\”JzIwOzEONTM3MTOQWNTIOMZEwMzg4MjUZMTswMDsn\”"”, 

"id": "0115971e-df3a-ed11-bbae-6045bd8e554a", 

"ernels a ms. 

"displayName": "Cost and Freight", 

"lastModifiedDateTime": “2022-09-23T01:29:40.0832” 


BUSINESS CENTRAL ENTITY: 


Shipment Methods 


O Search é EŠ Edit Lit — [5 Delete y More options 


Cost and Freight 
Cost Insurance and Freight 
Carriage and Insurance Paid 


Carriage Paid to 


Malmwearad at Erentiar 
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GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /shipmentMethods 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /shipmentMethods (0115971e-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 
"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/shipmentMethods”, 
Dove EMI 
{ 
"Qodata.etag": “W/\”JzIwOzEONTM3MTOWNTIOMZEwMzg4MjUZMTswMDsn\”"”, 
"id": “011597le-df3a-ed1l1-bbae-6045bd8e554a”, 
Decode: DCER, 
"displayName": "Cost and Freight", 
"lastModifiedDateTime": “2022-09-23T01:29:40.0832” 


"Qodata.etag": "W/N"JzIwOzEONTM3MTIzMTUwODCINDUINTYzMTswMDsnV"^", 
"id": "0215971e-df3a-edl1-bbae-6045bd8e554a", 

Deodet eq 

"displayName": "Cost Insurance and Freight", 
"lastModifiedDateTime": “2022-09-23T01:29:40.0972” 


"Qodata.etag": "W/N"JzIwOzEONTM3MTEA4NzEONjglOtgxMzc2MTswMDsn'N"", 
"id": "0315971e-df3a-edl1l-bbae-6045bd8e554a", 

peodod M PI 

"displayName": "Carriage and Insurance Paid", 
"lastModifiedDateTime": “2022-09-23T01:29:40.0972” 


}, 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /shipmentMethods 


Example POST Request Body: 


BCOde aaa) WO, 
"displayName": “Drone Drop Off" 
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Example POST Response: 


{ 

"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadata#companies ({{companyID}})/shipmentMethods/Sentity”, 

"Qodata.etag": “W/\”JzIwOzEONTM20TMyOTOxNDUZNzgzOTO4MTswMDsn\"”, 

Maid) “30/2472 7/8 —e256-edll—8e34-6045bda91 i647, 

Scode DUO 

"displayName": “Drone Drop Off", 

“lastModifiedDateTime”: "2022-10-28T13:14:37.322" 


} 
PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /shipmentMethods (30247278-c256-ed11-8c34-6045bda91864) 


Example PATCH Request Body: 


negde: DEDI 
"displayName": “Drop-off By Drone” 


Example PATCH Response: 


{ 

"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/shipmentMethods/Sentity”, 

"Qodata.etag": “W/\”JzIwOzEONTM20TM2MDkzOTU2NzkzMTM4MTswMDsn\"”, 

"id": "30247278-c256-ed11-8c34-6045bda91864", 

eode: XDBDO 

"displayName": “Drop-off By Drone”, 

WilaistModtivedbateLime, = 2022 —lO—2 9 I S oT DIDI 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /shipmentMethods (30247278-c256-ed11-8c34-6045bda918 64) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 
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CREATING 


The Shipment Methods list is editable, so simply create a new entry. 


Shipment Methods v Saved 


Ø Search -++ New EZ Edit List fi] Delete Eş Translation More options 


Description 
CFR : Cost and Freight 
CIF Cost Insurance and Freight 
CIP Carriage and Insurance Paid 
CPT Carriage Paid to 
DAF Delivered at Frontier 
DDP Delivered Duty Paid 
DDU Delivered Duty Unpaid 
DELIVERY DELIVERY 
DEQ Delivered ex Quay 


UPDATING 


Alter a field, such as the Description. 


DELETING 


While you generally should not delete a Shipment Method if it is in use, you can test 
deletion by creating a new entry for the purpose of deletion. 


Bound Actions 


No bound actions. 


No navigations. 


History 


No notable changes. 
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Chapter 84: Tax Areas 


In Business Central, the Tax information often comes from a combination of the business 
partner (Customer or Vendor) and the traded item/service. 


The Tax Area is a meta-layer endpoint that depends on the setting in the General Ledger 
Setup that controls whether the company will Use VAT. 


If Use VAT is enabled, the Tax Area will give access to the VAT Business Posting Group 
information. 


If Use VAT is disabled, the Tax Area will give access to the Tax Area information. 


Primary Key 


Depending on the General Ledger Setup Use VAT flag. 


If Enabled: 
Code The identifier for the VAT Business Posting Group. The field is 20 
characters and alphanumeric. 
If Disabled: 
Code The identifier for the Tax Area. The field is 20 characters and 


alphanumeric. 


Field Map 


API JsoN: 


{ 
"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/taxAreas/Sentity”, 
“@odata.etag”: "W/N"JzE5SOzQ2NDQyODMANzUA4OTYOMzQxNTQxOzAwOyc- V", 
"id": "46572523-df3a-edll-bbae-6045bd8e554a", 


"code": “ATLANTA, GA”, 

"displayName": “ATLANTA, GA", 

Dre voss Voalss S00 ONT 
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“lastModifiedDateTime”: “2022-09-23T01:29:46.492” 


BUSINESS CENTRAL ENTITY: 


Depending on the General Ledger Setup Use VAT flag. 
If Enabled: 


VAT Business Posting Y Qups 


/2 Search sw — Bx Edit List [ll] Delete 


More options 


Code Î Description 


DOMESTIC 
EU 


Domestic customers and vendors 


Customers and vendors in EU 


EXPORT Other customers and vendors (not EU) 


taxType will be set to VAT. 


If Disabled: 


Tax Areas 


LQ Search +4 FE Edit List p L Edit “© View 


Code f Description 
> ATLANTA, GA : ATLANTA, GA 
CHICAGO, IL CHICAGO, IL 


MIAMI, FL MIAMI, FL 


N.ATL., GA Atlanta, GA - North 


taxType will be set to Sales_x0020_Tax. 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/taxAreas 
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Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /taxAreas (46572523-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (4 entities shown from a potentially longer list): 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/taxAreas”, 

“value”: [ 


{ 


"Qodata.etag": “W/\"”JzE50zQ2NDQyODM4NzU40TY 0MzOxNTOxOzAwOyc=\"", 
"id": "46572523-df3a-edll-bbae-6045bd8e554a", 

"code": “ATLANTA, GA”, 

"displayName": “ATLANTA, GA”, 

Deaxhype@: MS akesm <0 070M Masai, 

"lastModifiedDateTime": “2022-09-23T01:29:46.492” 


"Qodata.etag": “W/\”JzE50zQ02NDQ1MzIyNDcyNzE1Njc3MdgxOzAwOyc=\"", 
"id": "47572523-df3a-edll-bbae-6045bd8e554a", 

Neocles Celso dO 

"displayName": "CHICAGO, IL", 

"upebxibwrers s “Seles! s0020 Were”, 

"lastModifiedDateTime": “2022-09-23T01:29:46.492” 


"Qodata.etag": "W/N"JzESOzQ2NDQxNTI5MjcONjQzMTAwOTgxOzAwOyc-NV"", 
"id": "48572523-df3a-edll-bbae-6045bd8e554a", 

Meodod MI AMI ESSA 
"displayName": "MIAMI, FL", 
Viaxchyped: SSallese<0 0200 T asc 


"lastModifiedDateTime": "2022-09-23T01:29:46.5072" 


"Qodata.etag": "W/N"JzES5OzQ2NDMAMjEyODCANjIyNTUINjgxOzAwOyc-^N"", 
"id": "49572523-df3a-edll-bbae-6045bd8e554a", 

Newel DN ATINA GAT 
"displayName": "Atlanta, GA - North”, 

Miers Sede MOZO "Merz 
peliareMecaseurecbatemed 029 Om polo ORIZMG 


POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{{tenantID}}/APIBook/api/v2.0/compa 
nies ({companyID}})/taxAreas 


Example POST Request Body: 


Meode/- YGa lact rey 
“displayName”: “Galactical customers and vendors” 
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Example POST Response: 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/$metadatafcompanies(((companyID]])/taxAreas/$entity", 
"Qodata.etag": "W/N"JzE5OzQ2MjE2MDQ4ODYwNjOlNTYwNTOxOzAwOyc-V"", 
"id": "0b09a194-c356-ed11-8c34-6045bda91864", 
"code": "GALACTIC", 
"displayName": "Galactical customers and vendors", 
Dtaxhype s sakes MOZO Masa, 
WiastMedMeved Da relames:s 7022-10 POTINS 


} 
PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /taxAreas (0b09a194-c356-ed11-8c34-6045bda91864) 


Example PATCH Request Body: 


“code”: “International”, 
"displayName": “International customers and vendors” 


Example PATCH Response: 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/$metadatafcompanies(((companyID]])/taxAreas/$entity", 

"Qodata.etag": "W/N"JzE5OzQ2MjE3OTEONzgxMTEANzOINTIxOzAwOyc-^N"", 

"id": "0b09a194-c356-ed11-8c34-6045bda91864", 

"code": "INTERNATIONAL", 

"displayName": "International customers and vendors", 

Miers "B “Seles s0020 "eps e 

peiarsiMecaseurecibateTmed ql? TM P OTIO 


DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/taxAreas (0b09a194-c356-ed11-8c34-6045bda91864) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


PART 7: VARIOUS 
CHAPTER 84: TAX AREAS 


CRUD Steps 


CREATING 
The Tax Area or VAT Business Posting Group list is editable. So, simply create a new 
entry. 
UPDATING 


The Tax Area or VAT Business Posting Group list in Business Central is directly editable. 
So, open the list and change a line, such as the Description field. 


DELETING 


The Tax Area or VAT Business Posting Group list in Business Central is directly editable. 
So, open the list and delete a line. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


History 


No notable changes. 
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Chapter 85: Tax Groups 


In Business Central, the Tax information often comes from a combination of the business 
partner (Customer or Vendor) and the traded item/service. 


The Tax Group is a meta-layer endpoint that depends on the setting in the General Ledger 
Setup that controls if the company will Use VAT. 


If Use VAT is enabled, the Tax Group will give access to the VAT Product Posting Group 
information. 


If Use VAT is disabled, the Tax Group will give access to the Tax Group information. 


Primary Key 


Depending on the General Ledger Setup Use VAT flag. 


If Enabled: 
Code The identifier for the VAT Product Posting Group. The field is 20 
characters and alphanumeric. 
If Disabled: 
Code The identifier for the Tax Group. The field is 20 characters and 


alphanumeric. 


Field Map 


API JSON: 


{ 
"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/taxGroups/Sentity”, 
"Qodata.etag": "W/N"JzE5OzQ2NDAOMTcwMjO4NDM2NTIA4OTIxOzAwOyc-V"", 
"id": "56572523-df3a-edll-bbae-6045bd8e554a", 
"code": "FURNITURE", 
"displayName": "Taxable Olympic Furniture", 
Dre voss Voalss Q020 Max’, 
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"lastModifiedDateTime": “2022-09-23T01:29:46.5872” 


BUSINESS CENTRAL ENTITY: 


Depending on the General Ledger Setup Use VAT flag. 
If Enabled: 


VAT Product Posting G 


PL Search EF Edit List [i] Delete 


Code f Description 

FULL NORM : VAT Only Invoices 25% 
FULL RED VAT Only Invoices 10% 
REDUCED Reduced VAT (10%) 
SERV NORM Miscellaneous 25 VAT 


SERV RED Miscellaneous 10 VAT 


taxType will be set to VAT. 


If Disabled: 


Tax Groups 


2 Search E? Edit List lif Delete 


Code f Description 


FURNITURE Taxable Olympic Furniture 
LABOR Labor on Job 
MATERIALS Taxable Raw Materials 


NONTAYARIE Nantavahla 


taxType will be set to Sales_x0020_Tax. 


GET 


Example GET Request URI List: 
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https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}})/taxGroups 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /taxGroups (56572523-df3a-ed11-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/taxGroups”, 
“value”: [ 
{ 
"Qodata.etag": "W/N"JzE5OzQ2NDAOMTcwMjO4NDM2NTIA4OTIxOzAwOyc-V"", 
"id": "56572523-df3a-ed11-bbae-6045bd8e554a", 
coder SEURNT TURE S 
"displayName": “Taxable Olympic Furniture”, 
Witemabyosg "eyes 0102/0) Utter”, 
"lastModifiedDateTime": “2022-09-23T01:29:46.5872” 


"Qodata.etag": “W/\”JzE50z02MzkxNDO3MzgxNzU3NzkwNTcxOzAwOyc=\"", 
"id": "57572523-df3a-edll-bbae-6045bd8e554a", 

coden = SEABORZ, 

"displayName": "Labor on Job”, 

PipEbXIbwgers s “Sales MOZO Were”, 

MilastModltitedDateiimei DZ 020o STOE ORSZ 


"Qodata.etag": “W/\"”JzE50z02Mzg3NzE3NTCOM)k3NzIwMTQxOzAwOyc=\"", 
"id": "58572523-df3a-edll-bbae-6045bd8e554a", 

“code”: “MATERIALS”, 

"displayName": “Taxable Raw Materials”, 

"upebxibwrers "8 “Seles: S020 Were”, 

NU astModu tiecdbatedsime^:9y2022: 919 29] 05:29 168 5/9907) 


), 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID]))/taxGroups 


Example POST Request Body: 


"code": "Extreme VAT", 
"displayName": "Extreme VAT (75$)" 


Example POST Response: 
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“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/taxGroups/Sentity”, 

"Qodata.etag": “W/\"JzE50zQ2Nz15MjE20DU2Mj kyODEyOTAxOzAwOyc=\"", 

"id": "f9c1c488-c456-ed11-8c34-6045bda91864", 

“code”: “EXTREME VAT", 

"displayName": “Extreme VAT (75%)”, 

Sree typer SSales ex 0020) T as, 

SlastMeoditivedbateLime. = 2022-10: 29] 9:52:91 2/667) 


} 
PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /taxGroups (£9c1c488-c456-ed11-8c34-6045bda91864) 


Example PATCH Request Body: 


"displayName": “Unrealistic VAT (75%)” 


Example PATCH Response: 


{ 

"Qodata.context": “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}})/taxGroups/Sentity”, 

"Qodata.etag": “W/\”JzE50zQ2NzZI5MjExNZMINTkyODI4MDAxOzAwOyc=\"", 

"id": "f9c1c488-c456-ed11-8c34-6045bda91864", 

Neode” >? “EXTREME, VAT’, 

"displayName": “Unrealistic VAT (75%)”, 

Pupebxibwrere g Seules) MOZO Were”, 

altas M ocisturesbatsedume 8920/2: AES? Olio S VP IO MEDIO] UE 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /taxGroups (£9c1c488-c456-ed11-8c34-6045bda91864) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
“No Content". 


CRUD Steps 


CREATING 
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The Tax Group or VAT Product Posting Group list is editable. So, simply create a new 
entry. 
UPDATING 
The Tax Group or VAT Product Posting Group list in Business Central is directly editable. 
So, open the list and change a line, such as the Description field. 
DELETING 


The Tax Group or VAT Product Posting Group list in Business Central is directly editable. 
So, open the list and delete a line. 


Bound Actions 


No bound actions. 


Navigations 


No navigations. 


History 


No notable changes. 
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Chapter 86: Units of Measure 


The Units of Measure is noted on Items, as well as on Sales and Purchase Documents (on 
the line). This endpoint allows you to access the description of the Unit of Measure in use. 


Primary Key 


Code The identifier for the given Unit of Measure. The field is 10 characters 
and alphanumeric. 


Field Map 


API JSON: 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({{companyID}}) /unitsOfMeasure/Sentity”, 
“@odata.etag”: “W/\”JzIwOzE2NDkyNjEwODYONTYZNDMOMzg3MTswMDsn\”"”, 


"id": “e215971le-df3a-ed1l1-bbae-6045bd8e554a”, 
Decode: “PACK, 

"displayName": “Pack”, 
"internationalStandardCode": “PK”, 

gsm ola 

“lastModifiedDateTime”: "2022-09-23T01:29:44.1932" 


BUSINESS CENTRAL ENTITY: 
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Units of Measure 


Ez Edit List More options 


nternationa! Standard 


Code 
BX 
CA 


GET 


Example GET Request URI List: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /unitsOfMeasure 


Example GET Request URI Single: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /unitsOfMeasure (e215971e-df3a-edll-bbae-6045bd8e554a) 


Example GET Response (3 entities shown from a longer list): 


{ 

“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}})/unitsOfMeasure”, 

“value”: [ 


{ 
"Qodata.etag": “W/\”JzIwOzE2NjIxMDgwODcxODE1NjkwMzYOMTswMDsn\”"”, 
"id": "db15971e-df3a-edll-bbae-6045bd8e554a", 
Ncodel BOX 
"displayName": "Box", 
"internationalStandardCode": “BX”, 
vam en A 
"lastModifiedDateTime": "2022-09-23T01:29:44.1472" 

}, 

{ 
"Qodata.etag": "W/N"JzIwOzE2NTg4NzUxMjMwNzIzODcxNTMyMTswMDsnV"" , 
"id": "dc15971e-df3a-edll-bbae-6045bd8e554a^, 
Decode: SCANN, 
"displayName": “Can”, 
"internationalStandardCode": "CA", 
Nery lg ww. 
“lastModifiedDateTime”: “2022-09-23T01:29:44.162” 

), 

1 
"Qodata.etag": "W/N"JzIwOzE2NtcwMzgyMjQ50TOQ2Mj IwMzIxMTswMDsn'N"", 
"id": "dd15971e-df3a-ed1ll-bbae-6045bd8e554a^", 
Scode a DAY 
"displayName": "Day", 
"internationalStandardCode": "DAY", 
sm oa S47, 
"lastModifiedDateTime": “2022-09-23T01:29:44.162” 

}, 
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POST 


Example POST Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies ({companyID}}) /unitsOfMeasure 


Example POST Request Body: 


"oogde: SM 
"displayName": “Full Moon", 
« internationalStandardCode » : « FM » 


Example POST Response : 


{ 

« @odata.context » : « https ://api.businesscentral.dynamics.com/v2.0/{{tenan 
tID}}/APIBook/api/v2.0/Smetadata#companies ({ {companyID}}) /unitsOfMeasure/Sentity 
5» 


« Qodata.etag » : « W/N »JzIwOzE20TMA4Mzc4NjI2MTkONzEzNzA5MTswMDsnN » », 
«udi»: «32539211095 c065!6-ed1].—8/:094-:6045] 38239664.» 

Decode: DEM, 

"displayName": “Full Moon", 

"internationalStandardCode": "FM", 

Senwudoxol^g WU 

WilastModiitedDakeiimel: 7022: 2:94 9:710: :08]0599/6:9 71 


PATCH 


Example PATCH Request URI: 


https://api.businesscentral.dynamics.com/v2.0/((tenantID)]/APIBook/api/v2.0/compa 
nies((companyID)])/unitsOfMeasure (d2332105-c656-ed11-8c34-6045bda91864) 


Example PATCH Request Body: 


Seve SOSA, 
"displayName": "Boatload", 
"internationalStandardCode": "BL" 


Example PATCH Response: 


{ 
“@odata.context”: “https://api.businesscentral.dynamics.com/v2.0/{{tenantID} } 
/APIBook/api/v2.0/S$metadata#companies ({{companyID}}) /unitsOfMeasure/Sentity”, 
"Qodata.etag": "W/N"JzIwOzE20dkxNjEA4NDIyNjISNTIyNzMOMTswMDsn'N"", 
"id": "d2332105-c656-ed11-8c34-6045bda91864", 
meodcoc VB, 
"displayName": "Boatload", 


PART 7: VARIOUS 
CHAPTER 86: UNITS OF MEASURE 


"internationalStandardCode": "BL", 
symbole: ae 
"lastModifiedDateTime": “2022-10-28T13:41:08.1172” 


} 
DELETE 


Example DELETE Request URI: 


https://api.businesscentral.dynamics.com/v2.0/{ {tenantID} }/APIBook/api/v2.0/compa 
nies ({companyID}}) /unitsOfMeasure (d2332105-c656-ed11-8c34-6045bda91864) 


No request body is required. No response body will be given, only an HTTP Status of 204, 
"No Content". 


CRUD Steps 


CREATING 
The Units of Measure list is editable. So, simply create a new entry. 


Units of Measure 


J9 Search -+ New — BEEditlist [ii] Delete More options 


Description International Standard Code 
Box BX 

Can CA 

Day 

Hour 

Kilo 

Kilometer 


Miles 


UPDATING 


Alter a field, such as the Description. 


DELETING 


While you generally should not delete a Unit of Measure if it is in use, you can test deletion 
by creating a new entry for the purpose of deletion. 


PART 7: VARIOUS 
CHAPTER 86: UNITS OF MEASURE 


Bound Actions 


No bound actions. 


No navigations. 


History 


No notable changes. 
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PART 8: ADDITIONAL TOPICS 


This Part covers some key concepts, deeper understanding, and various other information 
that wasn't tied to a specific HTTP Operation or API Endpoint. 
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Chapter 87: Authentication 


When you call a Business Central API, it is required to authenticate, which means the 
request must include valid credentials to access Business Central data. The required credential 
type depends on the configuration of the Business Central server. 


Business Central online only supports OAuth authentication. On-premises environments 
can be configured to support Windows authentication, Basic authentication, or OAuth 
authentication. Within the scope of this book, we focus on OAuth authentication only. 


OAuth Authentication 


OAuth is an open standard for access delegation. It is commonly used by users to grant 
applications or websites access to their data without giving them their credentials. Instead, 
OAuth allows access tokens to be issued to third-party clients by an authorization server with 
the approval of the user. The third-party client uses the access token to access the protected 
data hosted by a server. OAuth provides specific flows for different types of applications to get 
an access token. 


in October 2012. The full description of the OAuth 2.0 
Authorization Framework is available here: https://www.rfc- 


editor.org/rfc/rfc6749 


Concepts in OAuth 


In OAuth terms, the data is referred to as a resource. The user is a resource owner, and 
the server that protects and provides the data is a resource server. In the context of this book, 
it is the Business Central server. 


eo Note: When we mention OAuth, we mean OAuth 2.0, as published 


The client application is the application that requests access to a protected resource. For 
example, a C£ application, an Azure Function, Postman or a PowerShell script. 
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The authorization server, the Microsoft identity platform, handles the end-user's 
information, their access, and the trust relationship between the resource owner and the client 
application. The diagram below shows the different parties in relation to each other. 


Authorization server 
Azure ^i Directory 


Business Central user 


(C 3 
Resource owner Client -~ g m 


Resource server 
Business Central 


The client application uses a series of steps (a flow) to obtain the user's permission to 
access the resource. The result of this flow is an access token, which is a so-called bearer token. 
Other bearer tokens are ID tokens and refresh tokens. Bearer tokens in the Microsoft identity 
platform are formatted as JSON Web Tokens (JWT). 


Account types 


Business Central supports two account types for client applications to authenticate using 
OAuth. Which one to use is the first decision you must make before anything else. 


e User account (user impersonation) 
e Application account (service-to-service) 


When a client application uses user impersonation, it represents an interactive and 
licensed user with an active user account in Business Central. A request made with user 
impersonation is running in the context of this user. The user must give consent for the client 
application Business Central. The client application will get access to all data the user has access 
to based on the permissions assigned to the user account. After acquiring an access token, the 
client application may use a refresh token to maintain access without requiring the user to log 
in again. 


When a client application is using service-to-service authentication, it represents a non- 
interactive user account. This is known as an application account in Business Central. An 
application account does not require a license. An administrator must consent access to 
Business Central to the client application. The client application will get access to the data 
based on the permissions assigned to the application account. A refresh token is not required 
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because the service-to-service authentication can acquire access tokens without an interactive 
login. 


the number of required user licenses. Any internal user that is 
accessing Business Central is required to have a license 
assigned, regardless of the authentication type that is used. 
See the Licensing Terms guide for more information about 
this. 


App registration 


The Microsoft identity platform needs a way to register the trust relationship between a 
client application and a resource owner. This is done by registering a client application with the 
identity platform in Entra ID (formerly Azure Active Directory or Azure AD). During the 
registration, a several settings have to be configured, depending on how the client application 
will be used. In the next paragraphs, we will discuss each setting in detail. 


i) Note: Service-to-service authentication cannot be used to limit 


To start the app registration, open the Entra ID admin portal at 
https://aad.portal.azure.com/ (the URL still works to jump to Entra's Identity Overview) Then 
go to Applications and click on App Registrations. 


Here is a direct link to App registrations: 


https://entra.microsoft.com/#view/Microsoft AAD RegisteredApps/Applications 
ListBlade/quickStartType~/null/sourceType/Microsoft AAD IAM 


At the top of the list of app registration, click on New registration to start the process of 
registering a new client application in Entra ID. 
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Microsoft Entra admin center Ø Search resources, services, and docs (G+/) [al 


* Home > Contoso App registrations 


Home 


Register an application 


What's new 


Diagnose & solve problems * Name 


The user-facing display name for this application (this can be changed later). 
Favorites 


My Business Central Integration 


Identity 
Supported account types 
Overview 
Who can use this application or access this API? 


JESS © Accounts in this organizational directory only (Contoso only - Single tenant) 


Groups Q Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) 


O Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, 
Devices Xbox) 


O Personal Microsoft accounts only 
Applications 


Help me choose... 
Enterprise applications 


App registrations Redirect URI (optional) 


Roles & admins We'll return the authentication response to this URI after successfully authenticating the user. Providing this now is optional and it can be 
changed later, but a value is required for most authentication scenarios. 


Protection = : 
Select a platform vV | | eg. https://example.com/auth 


STB ASENEN ED Register an app you're working on here. Integrate gallery apps and other apps from outside your organization by adding from Enterprise applications. 


A External Identities 


By proceeding, you agree to the Microsoft Platform Policies (7? 


i Learn & support 


Provide a name for the new app, e.g., My Business Central Integration. Under the section 
Supported account types, choose between the first two options. The last two options are only 
used for Business to Consumer (B2C) scenarios with personal Microsoft accounts. 


If the client application is only used by accounts within the Entra ID Tenant in which the 
client application is registered, then choose Single tenant. 


If the client application is used by accounts in other Entra ID Tenants from other 
organizations, choose Multitenant. 


Keep in mind that the app registration is not part of the source code of the client 
application and can be reused everywhere the application runs. Every individual installation of 
the application should be considered a separate application and may require its own app 
registration in Entra ID. 


In other words, an application installed at multiple organizations may need its own single- 
tenant app registration in the Entra ID of that organization. However, this also depends on the 
context of how an application is used. Please consider carefully what the best option is for a 
given application. 


A centrally hosted and managed application that is used by multiple organizations, for 
example, a webshop, can use one multitenant app registration because it is used by users from 
multiple Entra ID Tenants. 


The section Redirect URI is optional and can also be configured later, but the commonly 
needed one for Business Central is (case-sensitive): 
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https://businesscentral.dynamics.com/OAuthLanding.htm 


Home > Contoso > App registrations 


ua My Business Central Integration 2 


P Search la] Delete e Endpoints fal Preview features 


HR Overview @ Gota second? We would love your feedback on Microsoft identity platform (previously Azure AD for developer). — 


&> Quickstart 
* Integration assistant A Essentials 


X Diagnose and solve problems Display name Client credentials 
My Business Central Integration icate or secret 


Manage Application (client) ID fem Redirect URIs 


01d3e611-c8c7-4e3d-9f17-ed62030600d9 Add a Redirect URI 
ES Branding & properties ———————————————— 
Object ID Application ID URI 


D Authentication 1die4b25-7e0f-446a-b496-13bed69ed865 Add an Application ID URI 


? Certificates & secrets Directory (tenant) ID Managed application in local directory 
d6738d9b-6610-4ec3-b113-fd740095fa95 My Business Central Integration 

" 

Wi Token configuration Supported account types 


> API permissions Multiple organizations 


@ Expose an API 
@ Welcome to the new and improved App registrations, Looking to learn how it's changed from App registrations (Legad 


Fi App roles more 


âs Owners 
@ Starting June 30th, 2020 we will no longer add any new features to Azure Active Directory Authentication Library (ADA 
&, Roles and administrators Azure Active Directory Graph. We will continue to provide technical support and security updates but we will no longe 


feature updates. Applications will need to be upgraded to Microsoft Authentication Library (MSAL) and Microsoft Grag 
fl Manifest more 


On the overview, the Application ID, also known as the Client ID, is an important value. 
It is a unique identifier for this app registration across all Entra ID Tenants. It is used to identify 
the app when acquiring an access token. It is also part of the access token to let the resource 
server know which application is calling the API. 


The next steps are to further configure the app registration. The settings that need to be 
configured are: 


e Redirect URI 
e Secrets 
e API permissions 


All three settings are connected. The redirect URI determines if a secret is required. The 
API permissions influences both redirect URI and secret. Moreover, the API permissions depend 
on the account type. Before discussing different scenarios, it is important to understand the 
three settings mentioned above. 


REDIRECT URI 


The redirect URI is required when an active user is logging in and giving consent to the 
application. The application opens a login window that points to the login page of the 
Microsoft Identity platform. When the login procedure is ready, the Microsoft Identity platform 
navigates the user back to the application, which is called the redirect URI. It must be a page 
that is owned by the application. At the end of the redirect URI, a code is added, and the 
authorization grants the code. The application can use this code to redeem it for an access 
token. The redirect URI will be discussed in more detail later in this chapter. 
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SECRET 


A secret is, in fact, a password. In the Entra ID portal, it is called a secret, but in the Graph 
API behind it is called a password. Together with the client id, they form the credentials of an 
app registration. A secret is generated by the Entra ID portal and has an expiration period of 
up to 24 months. When the secret is about to expire, a new secret should be created. 


Because of this expiration period, it is recommended to generate at least two secrets with 
different expiration periods. 


Not all app registrations need a secret, as it depends on how the redirect URI is registered. 
See the scenarios below for more information about the redirect URI and when a secret is 
required. 


To create a secret: 
1- Click on Certificates & Secrets in the left menu. 
2- Select Client secrets if it is not already selected. 
3- Click on New client secret. 
4- Provide a description (optional) and an expiration period. 
5- Click on Add. 
The screen will now look like the following: 


Home > Contoso > App registrations > My Business Central Integration 


? My Business Central Integration | Certificates & secrets 2 


Ø Search | A Got feedback? 


iE Overview 
& Quickstart @ Gota second to give us some feedback? —> 


# Integration assistant 

Credentials enable confidential applications to identify themselves to the authentication service when receiving tokens at a web addressable 
location (using an HTTPS scheme). For a higher level of assurance, we recommend using a certificate (instead of a client secret) as a 
credential. 


X Diagnose and solve problems 


Manage 


ES Branding & properties 

© Application registration certificates, secrets and federated credentials can be found in the tabs below. 
3 Authentication 

? Certificates & secrets 


P Certificates (0) Client secrets (1) Federated credentials (0) 
1l! Token configuration 


> API permissions A secret string that the application uses to prove its identity when requesting a token. Also can be referred to as application password. 


@ Expose an API 
ü ++ New client secret 
Ei App roles 

Description Expires Value ( Secret ID 
& Owners 

Example API 8/12/2026 zQS8Q-IhKBvnQxKyXyFoSgn.. ® 5ec2a316-9cc2-4d9a-bí4d-8.. (à [8 
& Roles and administrators 


Hl Manifest 


Make a copy of the secret Value by clicking the copy button behind it. The value will only 
be visible for a short time. If you navigate away, it will disappear, and there will be no way to 
recover it. 
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use a certificate. Secrets are good for development and test 
environments. However, for production environments, 
please consider using certificates. 


(i, Note: For a higher level of assurance, it is recommended to 


API PERMISSIONS 


The API permissions limit the application's access to a resource. A resource defines what 
permissions are available. A permission can be defined as delegated permissions or application 
permissions. Delegated permissions let the application access the resource on behalf of an 
interactive and logged-in user. This is also known as user impersonation. Application 
permissions are used to access the resource with its own application account and are used for 
service-to-service authentication. See also the paragraph about Account types earlier in this 
chapter. 


The available permissions for Business Central are: 


Permission Description 
Delegated permissions user_impersonation Access as the signed-in user 


Application permissions API.ReadWrite.All Full access to all APIs 


(including automation APIs) 


Automation.ReadWrite.All Full access to automation APIs 


AdminCenter.ReadWrite.All Full access to the Admin Center 
APIs 
The combination of a resource identifier and permission is called a scope. The resource 
identifier of Business Central is: 


https://api.businesscentral.dynamics.com 


A scope will then look like: 


https://api.businesscentral.dynamics.com/user impersonation 


There are two ways to request permissions for an app registration. The first way is to 
define the permissions in the Entra portal at the app registration. This is known as static 
permissions. However, this does not mean that the permissions have already been consented 
to. Every individual user still needs to grant those permissions. 


If static permissions are used, the scope does not have to mention a specific permission. 
Instead, the word "default" is used as permission: 


https://api.businesscentral.dynamics.com/.default 


Another way to request permissions is to request them during the login procedure. In 
that case, full permission must be defined in the scope. 
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Because application permissions are used for service-to-service authentication, with no 
logged-in user, there must be a different way to grant the permissions. Application permissions 
can only be defined in the app registration as static permissions. The administrator user must 
then grant permissions. This can be done in the Entra portal on the API permissions page of 
the app registration or with a specially constructed URL. 


To configure the static permissions, click on API permissions in the left menu of the app 
registration. By default, the app has one delegated permission: User .Read. If no other 
permissions have been configured yet, the page will look like this: 


Home > Contoso > App registrations » My Business Central Integration 


-æ My Business Central Integration | API permissions  ? 


[2 Search | © Refresh & Got feedback? 


IE Overview 


& Quickstart 
Ay Granting tenant-wide consent may revoke permissions that have already been granted tenant-wide for that application. Permissions that 
3 integration assistant users have already granted on their own behalf aren't affected. Learn more 


X Diagnose and solve problems 


@ The "Admin consent required" column shows the default value for an organization. However, user consent can be customized per 
permission, user, or app. This column may not reflect the value in your organization, or in organizations where this app will be used. Learn 
more 


Manage 
© Branding & properties 


> Authentication à "em 
Configured permissions 


Certificates & t : 
f Certificates & secrets Applications are authorized to call APIs when they are granted permissions by users/admins as part of the consent process. The list of 


II) Token configuration configured permissions should include all the permissions the application needs. Learn more about permissions and consent 


> API permissions ++ Adda permission Grant admin consent for Contoso 


@ Expose an API API / Permissions n... Type Description Admin consent req... Status 


i l 
* App roles \ Microsoft Graph (1) 


ow: 
& Owners User.Read Delegated Sign in and read user profile 


&, Roles and administrators 


Hi Manifest "T : 
To view and manage consented permissions for individual apps, as well as your tenant's consent settings, try Enterprise applications. 


Click on Add a permission just above the list of permissions. A new overlay window will 
open with three tabs on it: 


e Microsoft APIs. 
e APIs my organization uses. 
e My APIs. 


The Business Central application is listed under Microsoft APIs. You may need to scroll 
down to find the tile for Dynamics 365 Business Central. 
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Home > Contoso > App registration Request API permissions 
-a My Business Centr 


Select an API 


| © Search | 


Microsoft APIs APIs my organization uses My APIs 
HR Overview t 

Commonly used Microsoft APIs 
® Quickstart 


# Integration assistant Microsoft Graph 


Take advantage of the tremendous amount of data in Office 365, Enterprise Mobility + Security, and Windows 10. 
Access Microsoft Entra ID, Excel, Intune, Outlook/Exchange, OneDrive, OneNote, SharePoint, Planner, and more 
through a single endpoint. 


X Diagnose and solve problems 


Manage 
m Branding & properties 


3 Authentication 
Azure Rights Management 


Dynamics 365 Business 
€ Certificates & secrets Services 


A^ Azure Service Management Central 


Allow validated users to read and write Programmatic access to much of the Programmatic access to data and 
protected content functionality available through functionality in Dynamics 365 Business 
the Azure portal Central 


ill Token configuration 
> API permissions 
@ Expose an API 


Ei App roles 
» Dynamics CRM I Intune rj Office 365 Management APIs 


Access the capabilities of CRM business Programmatic access to Intune data Retrieve information about user, admin, 
4. Roles and administrators software and ERP systems system, and policy actions and events 
from Office 365 and Microsoft Entra ID 
W Manifest activity logs 


& Owners 


Click on the tile to open the next screen. Now you need to choose between Delegated 
permissions and Application permissions. Again, choose Delegated permissions if the 
application will access Business Central on behalf of a logged-in user. Choose Application 
permissions for background processes or to access Business Central without a logged-in user. 


Home > Contoso > App registration Request API permissions 
-a My Business Centr 


< All APIs 
Dynamics 365 Business Central 


[2 Search 
https://dynamics.microsoft.com/business-central/overview/ Docs c? 


iE Overview What type of permissions does your application require? 


4À Quickstart 
Delegated permissions Application permissions 


3K Integration assistant Your application needs to access the API as the signed-in user, Your application runs as a background service or daemon without a 


: signed-in user. 
X Diagnose and solve problems 


Manage 
ES Branding & properties 
D Authentication 

Tf Certificates & secrets 
il} Token configuration 
> API permissions 

@ Expose an API 

Ei App roles 

4& Owners 

&, Roles and administrators 


Il Manifest 


Support + Troubleshooting 


À New support request 


Under Delegated permissions, two permissions are available: user_impersonation 
and Financials .ReadWrite.All. To directly call Business Central APIs , you need to select 
user impersonation. Choose Financials .ReadWrite.Al1 only if you want to use the 
Microsoft Graph API to call Business Central APls. This is not a common scenario. 
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Home > Contoso > App registration Request API permissions 
-a My Business Centr 


< All APIs 
[e Search 1 Dynamics 365 Business Central 
=, e https://dynamics.microsoft.com/business-central/overview/ Docs c? 


iE Overview What type of permissions does your application require? 


æ> Quickstart 
Delegated permissions Application permissions 

# Integration assistant Your application needs to access the API as the signed-in user. Your application runs as a background service or daemon without a 
signed-in user. 


X Diagnose and solve problems 


Manage Select permissions expand all 


raring properties [ JD Start typing a permission to filter these results 


Authentication 


Certificates & secrets @ The "Admin consent required" column shows the default value for an organization. However, user consent can be customized per 
permission, user, or app. This column may not reflect the value in your organization, or in organizations where this app will be used. Learn 

Token configuration more 

API permissions 


Expose an API Permission Admin consent required 


App roles W Other permissions 


Owners 


user impersonation © 
Roles and administrators Access as the signed-in user 


Manifest 
a W Financials 


TM 
ptt mm Financials.ReadWrite.All © 


& New support request 


Select user. impersonation and click Add permissions to close the window and 
return to the permissions overview. The indicator (1) after Dynamics 365 Business Central 
indicates how many permissions have been configured for this application. 


Home > Contoso > App registrations > My Business Central Integration 


-a My Business Central Integration | API permissions 2 


[2 Search « ©) Refresh | AP Got feedback? 
E Overview ^ 

À You are editing permission(s) to your application, users will have to consent even if they've already done so previously. 
& Quickstart 


# Integration assistant 

XX Diagnose and solve problems A, Granting tenant-wide consent may revoke permissions that have already been granted tenant-wide for that application. Permissions that 
users have already granted on their own behalf aren't affected. Learn more 

Manage 


E Branding & properties 
Hp @ The "Admin consent required" column shows the default value for an organization. However, user consent can be customized per 


permission, user, or app. This column may not reflect the value in your organization, or in organizations where this app will be used. Learn 


Authentication 
more 


Certificates & secrets 


Token configuration Configured permissions 

APIpenmisions Applications are authorized to call APIs when they are granted permissions by users/admins as part of the consent process. The list of 
configured permissions should include all the permissions the application needs. Learn more about permissions and consent 

Expose an API 


++ Adda permission w Grant admin consent for Contoso 
App roles 


Dia API / Permissions n... Type Description Admin consent req... Status 


Roles and administrators W Dynamics 365 Busin 
@ Manifest userimpersona Delegated ^ Access as the signed-in user 
\ Microsoft Graph (1) 


Support + Troubleshooting 


: User.Read Delegated — Sign in and read user profile 
& New support request 


To view and manage consented permissions for individual apps, as well as your tenant's consent settings, try Enterprise applications. 


To add application permissions for background processes, repeat the steps, but now click 
on Application permissions. The list of permissions starts with app access. This permission 
should be ignored; it is not used by Business Central. 
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Azure Active Directory admin center 


Dasht n mpan trations > My Business Centr. 


-æ My Business Central Integration | API permissions 


Select permissions 


Support * Troubleshooting 
@ Trouble 
B New support request 


Select the permission needed for the app and then click on Add permissions. The 
resulting list of configured permissions now looks like the following: 


Home > Contoso > App registration Request API permissions 
-a My Business Centr 


What type of permissions does your application require? 


[2 Search " Delegated permissions Application permissions 
Your application needs to access the API as the signed-in user. Your application runs as a background service or daemon without a 


i overview signed-in user. 


4 Quickstart 


# Integration assistant Select permissions 


X Diagnose and solve problems JD Start typing a permission to filter these results 


Manage Permission Admin consent required 


E Branding & properties WV Other permissions 


D Authentication 


app access © 


Tf Certificates & secrets Access according to the application's permissions in Dynamics 365 Business Central 


" 
II} Token configuration OF ENE 


> API permissions 
AdminCenter.ReadWrite.All © 


€ Expose an API Full access to Admin Center API 


Bi App roles 


4& Owners 
API.ReadWrite.All © 
Full access to web services API 


&, Roles and administrators 


Il Manifest 

V Automation 
Support + Troubleshooting 

E Automation.ReadWrite.All © 
B New support request 


Please note that this is not a common scenario. An app usually has either delegated 
permissions or application permissions. 


In the column Status, you can see the comment ‘Not granted for «tenant»' on the line 
of the application permissions. As explained before, the application permissions need to be 
granted by an administrator user. This can be done in several ways, depending on the situation. 


If the app is single-tenant, it will only be used inside the current Entra ID Tenant. In that 
case, you grant consent here in the Entra portal. This is the easiest way to do it. To do so, click 
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on Grant admin consent for <tenant> right above the list of permissions. A popup will ask 
for your confirmation. 


Home > Contoso > App registrations > My Business Central Integration 


-a My Business Central Integration | API permissions 2 


[2 Search ©) Refresh | § Got feedback? 
i Overview i " s 
Grant admin consent confirmation. 


4 Quickstart Do you want to grant consent for the requested permissions for all accounts in Contoso? This will update any existing 


"€ admin consent records this application already has to match what is listed below. 


X Diagnose and solve problems No 


Manage 


Branding & properties 
ge prop @ The “Admin consent required" column shows the default value for an organization. However, user consent can be customized per 


permission, user, or app. This column may not reflect the value in your organization, or in organizations where this app will be 


Authentication used. Learn more 


Certificates & secrets 


l! Token configuration Configured permissions 


API permissions Applications are authorized to call APIs when they are granted permissions by users/admins as part of the consent process. The list of 
configured permissions should include all the permissions the application needs. Learn more about permissions and consent 
Expose an API 


++ Adda permission w” Grant admin consent for Contoso 
App roles 


Owners API / Permissions n... Type Description Admin consent req... Status 


Roles and administrators \ Dynamics 365 Busin 


Manifest APLReadWrite/ Application Full access to web services API Å Not granted for Contoso 


: userimpersona Delegated ^ Access as the signed-in user 
Support + Troubleshooting 


: \ Microsoft Graph (1) 
B New support request 


User.Read Delegated — Sign in and read user profile 


Click on Yes, and the configured permissions will show that the permissions have been 
granted. 


Home > Contoso > App registrations > My Business Central Integration 


-a My Business Central Integration | API permissions 2 


[2 Search ©) Refresh 5? Got feedback? 
overview @ Successfully granted admin consent for the requested permissions, 


& Quickstart 

# Integration assistant 

X Diagnose and solve problems AÀ Granting tenant-wide consent may revoke permissions that have already been granted tenant-wide for that application. Permissions 
that users have already granted on their own behalf aren't affected. Learn more 

Manage 


Branding & properties 
ng ot propr @ The “Admin consent required" column shows the default value for an organization. However, user consent can be customized per 


permission, user, or app. This column may not reflect the value in your organization, or in organizations where this app will be 


Authentication used. Learn more 


Certificates & secrets 


I! Token configuration Configured permissions 
API permissions Applications are authorized to call APIs when they are granted permissions by users/admins as part of the consent process. The list of 
configured permissions should include all the permissions the application needs. Learn more about permissions and consent 
Expose an API 


< -]- Add a permission w” Grant admin consent for Contoso 
App roles 


Owners API / Permissions n... Type Description Admin consent req... Status 


Roles and administrators \ Dynamics 365 Busin 


Manifest APLReadWrite/ Application Full access to web services API @ Granted for Contoso 


| userimpersona Delegated ^ Access as the signed-in user © Granted for Contoso 
Support * Troubleshooting 


= \ Microsoft Graph (1) 
Ê New support request 
User.Read Delegated ^ Sign in and read user profile @ Granted for Contoso 


As you can see on the screen-print above, granting admin consent applies to all 
configured permissions, including delegated permissions. As a result, users will not be asked 
to grant consent during the login process individually. They only need to log in and will be 
immediately redirected to the redirect URI. 


If you do not want to grant consent to all permissions but only to the application 
permission, follow the procedure below. 
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In multi-tenant scenarios, the app can be used in this Entra ID Tenant and foreign Entra 
ID Tenants. Granting admin consent is still possible for the current Entra ID Tenant, but that 
does not apply to any other Entra ID Tenant. Granting admin consent to other Entra ID Tenants 
must be done by its administrator. The best way to do this is to run the grant admin process 
from Business Central. This is done at the Microsoft Entra Application Card. See the next 
paragraph for more information about this process. 


Registering the app in Business Central 


Apps using delegated permissions call Business Central APIs on behalf of a logged-in 
user. Therefore, no further action is required in Business Central. If the user has a valid account 
in Business Central, the app can call the APIs with the same permissions as assigned to the user 
account. 


Apps that use application permissions use their own account in Business Central. This is a 
special user account of type application. Accounts of this type are not visible in the usual user 
list but are listed on the Microsoft Entra Applications page. Here you can create new application 
accounts, enable or disable them, assign permissions, and grant consent. Without this 
application account in Business Central, the app cannot call Business Central APIs. 


Open the search box and type in Microsoft Entra Applications (or just entra). The page 
may already have one application with the description "Dynamics 365 Business Central for 
Virtual Tables", or more related to Power Platform. Click on New to open the card for creating 
a new application account. 


Microsoft Entra Application Card 


aff Grant Consent More options 


General 


Client ID {00000000-0000-0000-0000-000¢ User information 


Description User ID {00000000-0000-0000-0000-00... 


A r 
State Disabled User Name 


Contact Information User Telemetry ID 100000000-0000-0000-0000-00... 


Extension 


App ID (00000000-0000-0000-0000- --- 


App Name 


User Permission Sets = ax 83 Permissions 


Extension Name 


The Client ID can be found on the overview page of the application registration in the 
Entra portal. Copy the value and paste it into the field. The curly brackets are not required, they 
will be added automatically. 
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The Description field is mandatory. Give it a meaningful name so you can easily identify 
the application account. 


The next step is to enable the application account. This will create a new account in the 
User table. The ID and username of this user account are also visible on the card under User 
information. It is required to enable the account; otherwise, you cannot assign permissions, 
and the account cannot be used to call Business Central APIs. 


In the State field, select Enabled. A popup will ask for your confirmation to create a new 
user with the name of the description. Click on Yes to continue or No to go back. The page will 
now look like this. 


My Business Central Integration 


af Grant Consent 


General 


Client ID (01d3e611-c8c7-4e3d-9f17-ed... User information 
My Business Central Integration User ID {41f97be7-77a5-453b-9741-a3... 

Enabled User Name MY BUSINESS CENTRAL INTEG... 
User Telemetry ID. {d573cd7a-c87a-4840-b40f-30... 


You must set the State field to Disabled before you can ma... 


{00000000-0000-0000-0000-00... 


User Permission Sets 8I Permissions 


Permission Set 
n 


After enabling the application, the parts for User Groups and User Permission Sets will 
also be enabled. Scroll down to User Permission Sets and assign one or more permissions. 
Without permissions, the application account will still be unable to access any data. Selecting 
the minimum required permissions for the external application is recommended. Assigning the 
SUPER permission set is not allowed. 


If the application registration is single tenant, and you have already granted the 
permissions in the Entra portal, the application is ready to use. In case the permissions need to 
be assigned, e.g., in a multi-tenant situation in the foreign Entra ID tenant, the permission grant 
can be done from this page. 


The button Grant Consent in the action bar will open a popup window that requires an 
administrator to log in. It will then ask if you trust the app to access Business Central, and then 
it will redirect the popup to a landing page of Business Central to return the result. This landing 
page must be registered first at the application registration in the Entra portal. 


If you had not added the Redirect URI earlier, then in the app registration in the Entra 
portal, click on Authentication. Under Platform configurations, click on Add a platform. From 
the popup, select the option Web. Then under Redirect URIs, enter this URL: 
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https://businesscentral.dynamics.com/OAuthLanding.htm 


This value is case-sensitive! 


Home » Contoso > App registrations > My Business Central Integration Configure Web 
3 My Business Central Integration | Authentic 


< All platforms Quickstart — Docsp? 
D Search « A Got feedback? 
* Redirect URIs 
E Overview 
: : The URIs we will accept as destinations when returning authentication responses (tokens) 
& Quickstart Platform configurations after successfully authenticating or signing out users. The redirect URI you send in the 
request to the login server should match one listed here. Also referred to as reply URLs. Learn 
# Integration assistant Depending on the platform or device tl more about Redirect URIs and their restrictions 
. redirect URIs, specific authentication settir 
X Diagnose and solve problems https://businesscentral.dynamics.com/OAuthLanding.htm 


++ Adda platform 


M 
lanage Front-channel logout URL 


ES Branding & properties This is where we send a request to have the application clear the user's session data. This is 


CYPRUS Supported account types required for single sign-out to work correctly. 


e.g. https://example.com/logout 
mc Who can use this application or access thi 9 9 


oki congestion © Accounts in this organizational direct 
figurati 


Implicit grant and hybrid flows 
© Accounts in any organizational direct 

API permissions Request a token directly from the authorization endpoint. If the application has a single-page 
architecture (SPA) and doesn't use the authorization code flow, or if it invokes a web API via 
JavaScript, select both access tokens and ID tokens. For ASP.NET Core web apps and other 


web apps that use hybrid authentication, select only ID tokens. Learn more about tokens. 


Expose an API Help me decide... 


à App roles 


Select the tokens you would like to be issued by the authorization endpoint: 

Owners Å Due to temporary differences in supp 
accounts for an existing registration. | Access tokens (used for implicit flows) 

Roles and administrators editor. Learn more about these restric 


ID tokens (used for implicit and hybrid flows) 


Mi Manifest 

Support + Troubleshooting A, Starting November 9th, 2020 end use 
apps without verified publishers. Adc 

B New support request 


Click on Configure at the bottom to close the popup. The configured redirect URI will be 
visible in a box with the header Web. 


Home > Contoso > App registrations > My Business Central Integration 


3 My Business Central Integration | Authentication 2 


JD Search < A? Got feedback? 


E Overview 
© Quickstart Platform configurations 


# Integration assistant Depending on the platform or device this application is targeting, additional configuration may be required such as 
a redirect URIs, specific authentication settings, or fields specific to the platform. 
X Diagnose and solve problems 
++ Adda platform 
Manage 


E? Branding & properties 
Web Quickstart Docs? [ii] 


D Authentication ` 
Redirect URIs 


Certificates & ts 
N The URIs we will accept as destinations when returning authentication responses (tokens) after successfully authenticating 


or signing out users. The redirect URI you send in the request to the login server should match one listed here. Also referred 


Token configuration 
to as reply URLs. Learn more about Redirect URIs and their restrictions? 


API permissions 
https://businesscentral.dynamics.com/OAuthLanding.htm Ww 
Expose an API 


*] Add URI 
App roles 


Owners 


Roles and administrators Front-channel logout URL 


This is where we send a request to have the application clear the user's session data. This is required for single sign-out to 


Manifest work correctly. 


Support + Troubleshooting | eg. https://example.com/logout 


BN rt st 
E Hekate Implicit grant and hybrid flows 


The application registration is now ready to grant consent from Business Central. In 
Business Central, click on Grant Consent. First, you will see a popup that tells you it is waiting 
for a response and warns you not to close the page. A second popup page will then open. If 
that does not happen, check the browser to see if popups are allowed on the current website. 
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The second popup will start with a login prompt. You can select a known account or use 
another account. This must be an administrator account! After logging in, the page will ask to 
accept the requested permissions. 


EE Microsoft 


admin@ .onmicrosoft.com 


Permissions requested 


Review for your organization 


My Business Central Integration 
unverified 


This application is not published by Microsoft. 


This app would like to: 
w/ Access as the signed-in user 
w^ Full access to web services API 


w^ Sign in and read user profile 


If you accept, this app will get access to the specified resources for 
ali users in your organization. No one else will be prompted to 
review these permissions. 


Accepting these permissions means that you allow this app to use 
your data as specified in their terms of service and privacy 
statement. The publisher has not provided links to their terms 
for you to review. You can change these permissions at 
https://myapps.microsoft.com. Show details 


Does this app look suspicious? Report it here 


The list of requested permissions does not mention Business Central. Expand the 
permission Full access to web services API to see the full description. 


Click on Accept to accept the requested permissions. The window will now redirect to the 
landing page of Business Central and report that it has been completed. Business Central will 
show a message to confirm. 


€- Microsoft Entra Application Card (2) e T fa] 


My Business Central Integration 


3f* Grant Consent More options 
General 


Client ID {01d3e611-c8c7-4e3d-9f17-ed6... User information 


Description My Business Central Integration User ID (41f97be7-77a5-453b-9741-a37.. 


State 355 CENTRAL INTEGR... 


(©) Consent was given successfully. 
{e872-4840-b40F-304... 


Contact Information 
Extension {before you can mak. 
App ID 


App Name 


User Permission Sets =x & Permissions 
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Within the scope of this book, we cannot discuss all the different combinations and 
scenarios. Instead, we will cover three basic scenarios: 


e Desktop Application 
e Web Application 
e Background Application 


Each scenario has different settings for the configuration settings. 


SCENARIO 1: DESKTOP APPLICATION 


A desktop application can range from a simple command line application to a full-blown 
application with a user interface. However, they have one thing in common: access Business 
Central data on behalf of the logged-in user. 


If you want to call Business Central without a logged-in user, go to scenario 3. 


One of the main characteristics of a desktop application is that you do not control the 
environment it is running on. That means that it is hard to store a secret safely. Sooner or later, 
it will be discovered. Therefore, a desktop application is referred to as a public application. 


A public application does not use a secret. That sounds unsafe, but, in fact, it is not. Unlike 
a web application, the desktop application handles both; log-in of the user and getting the 
access token in the same process. It does not have to transfer confidential information to a 
back-end server to get an access token. Because of the architecture of a desktop application, 
the whole process happens inside the application. 


For a public application, only the Redirect URI needs to be configured. The URL depends 
on the application. Usually, a desktop application does not use a browser to let the user log in. 
Instead, it opens its own window that hosts a browser control. By doing so, it can monitor what 
happens in that window. If the browser control redirects to the expected URL, it can read the 
full URL, including the parameters and then close the login window. The URL does not even 
have to exist for this procedure. 


Entra ID also provides redirect URLs to be used by a desktop application. These point to 
an existing landing page hosted by Microsoft. However, the most common scenario is to 
specify http://localhost as the redirect URL. 


In the app registration window of the Entra portal, click on Authentication in the left 
menu. Under Platform configurations click on Add a platform. From the list of platforms, 
choose Mobile and desktop applications. 
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Home > Contoso > App registrations > My Business Central Integration Configure platforms 
3 My Business Central Integration | Authentic 


Web applications 
[2 Search « AP Got feedback? 


HR Overview Ch web E Sinole-paoe application 


& Quickstart Platform configurations Build, host, and deploy a web server Configure browser client applications 
application. .NET, Java, Python and progressive web applications. 
# Integration assistant Depending on the platform or device tl Javascript. 
redirect URIs, specific authentication settir 
* Diagnose and solve problems 
+ Adda platform 


Manage : o 
Mobile and desktop applications 


ES Branding & properties 
RES Web 
D Authentication e iOS / macOS Ñ Aid 


Redirect URIs 


$ Certificates & secrets Objective-C, Swift, Xamarin Java, Kotlin, Xamarin 


The URIs we will accept as destinatior 
1l! Token configuration or signing out users. The redirect URI 
to as reply URLs. Learn more about Rt 
© API permissions 
https://businesscentral.dynamics.ct 
@ Expose an API 
us Add URI Mobile and desktop 
W& App roles Ed applications 
Windows, UWP, Console, loT & 
Limited-entry Devices, Classic iOS + 
Front-channel logout URL Android 


& Owners 


&, Roles and administrators 
This is where we send a request to have tl 


Hl Manifest work correctly. 


Support + Troubleshooting | eg. https://example.com/logout 


& New support request - : 
et Implicit grant and hybrid flows 


Select one of the predefined URLs or type in your own custom URL. Click on Configure 
to close the window and return to the previous page. 


Home > Contoso > App registrations > My Business Central Integration 


3 My Business Central Integration | Authentication  * 


| JD Search | A? Got feedback? 


iE Overview 
Quickstart Platform configurations 


# Integration assistant Depending on the platform or device this application is targeting, additional configuration may be required such as 
P redirect URIs, specific authentication settings, or fields specific to the platform. 
X Diagnose and solve problems 


-+ Adda platform 
Manage 


ES Branding & properties 
Mobile and desktop applications Quickstart Docs? 
Redirect URIs 


Authentication 


Certificates & secrets š 

The URIs we will accept as destinations when returning authentication responses (tokens) after successfully authenticating 
Token configuration users, The redirect URI you send in the request to the login server should match one listed here. Also referred to as reply 
URLs. Learn more about Redirect URIs and their restrictions 7 


API permissions 


[] https://login.microsoftonline.com/common/oauth2/nativeclient D 
Expose an API 


M https://login.live.com/oauth20_desktop.srf (LiveSDK) D 
à App roles 


LJ msal01d3e61 1-c8c7-4e3d-9f17-ed62030600d9://auth (MSAL only) D 
Owners 

http://localhost 
Roles and administrators 


: Add URI 
Manifest 


The predefined URLs will also be visible here, together with the custom URLs. Because the 
URL has been defined under platform Mobile and desktop applications, no secret is required 
to retrieve the access token. 


A desktop application works perfectly with dynamic permissions. Static permissions are 
only required if you want to pre-consent the permissions for all users. In that case, follow the 
instructions discussed in the paragraph API Permissions. 


SCENARIO 2: WEB APPLICATION 
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A web application differs from a desktop application in that it usually consists of two 
parts: a server part and a user interface running in the browser. Traffic between the user 
interface and the server part travels over a network connection, usually the internet. The most 
common scenario for a web application is that the server part is responsible for calling external 
web services, like Business Central APIs. 


If you want to call Business Central without a logged-in user, go to scenario 3. 


The process of retrieving an access token is a little more complicated compared to a 
desktop application. The user interface lets the user log in and process the consent procedure. 
The resulting authorization code must be sent to the server application, which can be 
redeemed for an access token. See the schema earlier in this chapter for the different steps in 
this process. 


The user interface can either open a popup window with the login page or redirect the 
browser window to the login page. A popup window is the most common scenario. In both 
cases, the login page redirects the user back to a web application page with the resulting 
authorization code of the login process. This page must be capable of reading the parameters, 
and then forwarding them to the server. 


Consider a redirect page: 


https://www.mywebapplication.com/oauthlanding.htm 


The login process will then add the authorization code like this: 


https://www.mywebapplication.com/oauthlanding.htm?code-AB.123 


How this page should read the authorization code and itto the server is beyond the scope 
of this book. What is important here is to understand that the code is transferred from the 
browser to the server. This makes the code vulnerable; it could potentially leak to a malicious 
application. In fact, you should always consider that this information will leak at some point. 
Instead of trying to prevent leaking, it is better to prevent somebody from taking advantage 
of the code. 


This is where the secret comes into play. The server application receiving the authorization 
code must identify itself as being the same application. This is done with the application id and 
the secret. An application using a secret is referred to as a confidential application. 


In the app registration window of the Entra portal, click on Authentication in the left 
menu. Under Platform configurations click on Add a platform. From the list of platforms, 
choose Web. 
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Home > Contoso 


App registrations 


My Business Central Integration 


3 My Business Central Integration | Authentic 


| P& Search | 


IE Overview 
&> Quickstart 
*X Integration assistant 


* Diagnose and solve problems 


Manage 
Branding & properties 
Authentication 
Certificates & secrets 
Token configuration 
API permissions 
Expose an API 
App roles 
Owners 
Roles and administrators 


Manifest 


Support + Troubleshooting 


A Got feedback? 


Platform configurations 


Depending on the platform or device tl 
redirect URIs, specific authentication settit 


+ Adda platform 


Supported account types 


Who can use this application or access thi 


O Accounts in this organizational direct 


© Accounts in any organizational direct 


Help me decide... 


AX Due to temporary differences in supp 
accounts for an existing registration. | 
editor. Learn more about these restric 


Ay Starting November 9th, 2020 end use 
apps without verified publishers. Adc 


Configure platforms 


Web applications 


tz Single-page application 


Configure browser client applications 
and progressive web applications. 
Javascript. 


C web 
X 


Build, host, and deploy a web server 
application. .NET, Java, Python 


Mobile and desktop applications 


e iOS / macOS 


Objective-C, Swift, Xamarin 


Ñ Android 


Java, Kotlin, Xamarin 


A Mobile and desktop 
applications 
Windows, UWP, Console, loT & 
Limited-entry Devices, Classic iOS + 
Android 


Specify the redirect page for your web application. 


Home > Contoso > App registrations 


My Business Central Integration 


3 My Business Central Integration | Authentic 


[e Search | 


IE Overview 
&> Quickstart 
s Integration assistant 


X Diagnose and solve problems 


Manage 
Branding & properties 
Authentication 
Certificates & secrets 
Token configuration 
API permissions 
Expose an API 
App roles 
Owners 
Roles and administrators 


Manifest 


A Got feedback? 


Platform configurations 


Depending on the platform or device tl 
redirect URIs, specific authentication settir 


-+ Adda platform 


Supported account types 


Who can use this application or access thi 


Q Accounts in this organizational direct 


© Accounts in any organizational direct 
Help me decide... 
AX Due to temporary differences in supp 


accounts for an existing registration. | 
editor. Learn more about these restric 


Configure Web 


< All platforms Quickstart | Docs? 


* Redirect URIs 


The URIs we will accept as destinations when returning authentication responses (tokens) 
after successfully authenticating or signing out users. The redirect URI you send in the 
request to the login server should match one listed here. Also referred to as reply URLs. Learn 
more about Redirect URIs and their restrictions 


https://myawesomewebapp.com/OAuthLanding.htm 


Front-channel logout URL 


This is where we send a request to have the application clear the user's session data, This is 
required for single sign-out to work correctly. 


| e.g. https://example.com/logout 


Implicit grant and hybrid flows 


Request a token directly from the authorization endpoint. If the application has a single-page 
architecture (SPA) and doesn't use the authorization code flow, or if it invokes a web API via 
JavaScript, select both access tokens and ID tokens. For ASP.NET Core web apps and other 
web apps that use hybrid authentication, select only ID tokens. Learn more about tokens, 


Select the tokens you would like to be issued by the authorization endpoint: 


Access tokens (used for implicit flows) 


ID tokens (used for implicit and hybrid flows) 


Click on Configure to close the window and return to the previous page. 


Because the redirect URL is registered under the Web platform, a secret is also required . 


See the paragraph about secrets for more information. 


A web application works perfectly with dynamic permissions. Static permissions are only 
required if you want to pre-consent the permissions for all users. In that case, follow the 
instructions discussed in the paragraph API Permissions. 


SCENARIO 3: BACKGROUND APPLICATION 
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A background application, sometimes referred to as daemon application, is a program 
that runs continuously in the background and wakes up to handle periodic service requests, 
which often come from remote processes or timer events. Because there is no user interface, 
there is no logged-in user. Instead, the application will use its own account to call Business 
Central APIs. 


The required permissions should be of type Application, e.g., API. ReadWrite.Al1. 
Dynamic permissions cannot be used with a background application because no interactive 
user can grant permissions during a login process. Therefore, the only option is to use static 
permissions, meaning that permissions must be configured in the app registration in the Entra 
portal. See the paragraph API Permissions earlier in this chapter for more information about 
the different permission types and how they must be configured. 


The redirect URL is required in case granting the permissions should be done from 
Business Central. For single-tenant applications, the permissions can be granted directly in the 
Entra portal. In that case, no redirect URI is required. For other scenarios, the redirect URI must 
be configured. See the paragraph Registering the app in Business Central for more 
information about the redirect URI and how to set up the application account in Business 
Central. 


For application permissions, it is always required to use a secret. See the paragraph 
Secrets for more information. 


OAuth flows are essential processes for the authentication and authorization of resource 
owners and applications. Some OAuth flows enable users to enter credentials via an OAuth 
login prompt or for authentication without user involvement for background processes. 


Within the scope of this book, the two most used flow types will be discussed: 


e Authorization Code flow. 
e Client Credentials flow. 


AUTHORIZATION CODE FLOW 


The Authorization Code flow exchanges an authorization code for an access token. This 
flow type is a user-interactive process requiring the user to log in. Desktop and web 
applications using delegated permissions should use this flow type to get the access token. 


There are alternative flow types for interactive logins that are outside the scope of this book. 
The Authorization Code flow works as follows: 


(1) The user clicks on a login link in the application, and a login prompt is opened, 
either in the same window or a popup window. The URL will include the redirect 
URL that must be used after the login procedure (see step 2). The user i 
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credentials according to the enabled login options. If multi-factor 

authentication is enabled, this will also be part of the login process. 

If required, the user is shown a list of permissions that the application requires 

and asked to grant these permissions. This is only required when the user has 

never granted the required permissions before and no admin user has granted 

the permissions on behalf of the whole organization. The user is redirected to 

the redirect URL that was provided in step 1. A parameter with the authorization 

code will be added to the end of the redirect URL. 

(3) The application receives the authorization code and uses it with the client id 
and secret (if required) to request an access token from the authorization server. 

(4) The authorization server generates an access token and, optionally, a refresh 
token and provides them to the application. 

(5) The application uses the access token to gain access to the API on behalf of the 
user. 

(6) The resource server verifies the access token and returns the data to the 
application. 


(2 


— 


The following picture demonstrated the complete procedure: 


1. Authorization request ed 


2. Authorization grant Resource owner 
Business Central user 


LJ —— 3. Authorization grant + client credentials Qo 


4. Access token Authorization server 


Client application 
Azure Active Directory 


5. Access token 


6. Protected resource (data) Resource server 
Business Central 


Let us see in detail what the requests for these steps look like. The first step is to generate 
the login URL to get the authorization code. The base URL can be copied from the app 
registration in the Entra portal. 


Open the Overview page of the app registration, then click on Endpoints in the menu at 
the top of the page. Copy the OAuth 2.0 authorization endpoint (v2) from the popup. 
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Home > Contoso > App registration Endpoints 
E My Business Cent! 


OAuth 2.0 authorization endpoint (v2) 


£ Search https;//login.microsoftonline.com/organizations/oauth2/v2.0/authorize 


HE Overview OAuth 2.0 token endpoint (v2) 


& Quickstart https://login.microsoftonline.com/organizations/oauth2/v2.0/token 


# Integration assistant OAuth 2.0 authorization endpoint (v1) 


* Diagnose and solve problems https://login.microsoftonline.com/organizations/oauth2/authorize 


OAuth 2.0 token endpoint (v1) 
https://login.microsoftonline.com/organizations/oauth2/token 


Manage 


ES Branding & properties 
OpenID Connect metadata document 


3 
D Authentication https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration 


1 Certificates & secrets 
Microsoft Graph API endpoint 


Îl] Token configuration https://graph.microsoft.com 


> API permissions 
pens Federation metadata document 


@ Expose an API https;//login.microsoftonline.com/d6738d9b-6610-4ec3-b113-fd740095fa95/federationmetadata/2007-06/federationmetadata.xml 


Bi App roles WS-Federation sign-on endpoint 
2B Owners https://login.microsoftonline.com/d6738d9b-6610-4ec3-b113-fd740095fa95/wsfed 


& Roles and administrators SAML-P sign-on endpoint 
https://login.microsoftonline.com/d6738d9b-6610-4ec3-b113-fd740095fa95/saml2 


@ Manifest 


Support + Troubleshooting 


& New support request 


The organization ID of the current Entra ID tenant is part of the URL. This is only in case 
the application is configured as single-tenant. For multi-tenant applications, the organization 
ID will be replaced with the word organizations. 


Instead of organizations, the word common can also be used. It is, however, recommended 
to use organizations because common also supports personal Microsoft accounts. Business 
Central only supports organizational accounts; therefore, it is better to restrict the login procedure 
to these account types by using the word organizations. 


Add the required parameters to the login URL: 


Description 
client_id Assigned in the app Copy the value from the overview page in the app 
registration registration. 
response type code This indicates that the application expects to 
receive an authorization code on the redirect URL. 
response mode query It indicates that the code parameter on the redirect 
URL must be added in the query part of the URL, 
like: ?code- ABC123 
redirect uri As configured in the app This must be one of the configured redirect URLs. 
registration 


scope The required permission For dynamic permissions, use: 
https://api.businesscentral.dynamics.com/user impersonation 
For static permissions, use: 
https://api.businesscentral.dynamics.com/.default 


For a desktop application (public application), the login URL will look like the following 
(line breaks are added for readability reasons): 


https: //login.microsoftonline. com/23286865 -4c8b-4464-8b01-a20c74bb5824/oauth2/v2.@/authorize 
?client_id=42013473-4dcb-46b5-b906-dec7c6b433d1 ) 
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&response type-cod 

&response mode-query 

&redirect uri-http://localhost 
&scope-https://api.businesscentral.dynamics.com/user impersonation 


The login URL for a web application is almost the same; only the redirect uri 
parameter will be different: 


https://login.microsoftonline.com/23286865-4c8b-4464-8b01-a20c74bb5824/0auth2/v2.0/authorize 
?client id=42013473-4dcb-46b5-b906-dec7c6b433d1 

&response type-cod 

&response mode-query 

&redirect uri-https://www.mywebapplication.com/oauthlanding.htm 
&scope-https://api.businesscentral.dynamics.com/user impersonation 


After completing the login procedure, the user will be redirected to the specified redirect 
URL. This URL will look like the following: 


https://www.mywebapplication.com/oauthlanding.htm?code=0.AQwAQx 6Xw... 


There will be more parameters on this URL, but we will focus on the most important one. If 
there was an error during the login or the user denied the required permissions, the redirect URL 
will have an error parameter. 


After the authorization code has been received, the request can be made to retrieve the 
access token. This is a web request made by the application without further user interaction. 


The endpoint that should be used can also be copied from the app registration in the 
Entra portal. Open the endpoints from the overview page and copy OAuth 2.0 token endpoint 
(v2). 


The request is of type POST. All parameters are passed in the body, which must be of type 


x-www-form-urlencoded. 


Description 
grant type authorization code Indicates that we are using the Authorization 
Code grant flow. 


client id Same value as in the 
previous step 
code As retrieved on the The authorization code expires after 10 minutes. 
redirect URI 
redirect uri Same value as in the It is mandatory, so Azure can verify if the 
previous step authorization code was really provided to this 
URL. 
scope Same value as in the The authorization code is only valid for the 
previous step requested permissions. 
client secret Assigned in the Entra Required if the redirect URL is registered under the 
portal web platform (confidential application). 
If the redirect URL is registered under Mobile and 
desktop applications (public application) the 
client secret should not be provided. 
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Here is an example of the request to retrieve the access token for a confidential web 
application: 


POST https://login.microsoftonline.com/23286865-4c8b-4464-8b01- 
a20c74bb5824/oauth2/v2.0/token 

Content-Type: application/x-www-form-urlencoded 
grant_type=authorization code 

&client id=42013473-4dcb-46b5-b906-dec7c6b433d1 

&code- 0.AQwAQx 6Xw.. 

&redirect uri- https://www.mywebapplication.com/oauthlanding.htm 
&scope- https://api.businesscentral.dynamics.com/user impersonation 
&client secret-Gq-80-VlO .aU2mNhizqRX2zFLlAhRB-G30-gcvQ 


The response for this web request will be a JSON formatted response that contains the 
access token. It looks like: 


{ 
Meoldsil tyeta Voceri, 

"scope": "https://api.businesscentral.dynamics.com/user impersonation", 

Wexpisce se Aat 3954 

Woxbaexpuspesm n Ses, 

Nuccessacokenms 
"eyJOeXAiOiJKV1QiLCJhbGciOiJSUzIl1NiIsIng1dCI6IilLSTNROW5OUjdiUm9meG1lWm9YcWJIWkdl 
dyIsImtpZCI6IilLSTNROW5OUjdiUm9meGllWm9YcWJIWkdldyJ9.eyJhdWOiOiJodHRwczovL2FwaS5i 
dXNpbmVzc2NlbnRyYWwuZzHluYWlpY3MuY29tliwiaXNzIjoiaHROcHMOLy9zdHMud21uZG93cy5uZXQv 
jMyODYA4NjUtNGMAYi00NDYOLThiMDEtYTIwYzcOYmI1ODIOLyIsImlhdCI6MTY3NDMzMTAxMywibmJml;j 
oxNjcOMzMxMDEzLCJleHAiOjE2NzQzMzUxNjgsImFjcil6IjEiLCJhaW8iOiJBVlFBcS84VEFBQUFGSEt 
KZVdxQjZDYTZUZHJQaVB6eSszNlpDd3klRFhKdaGJsWXdBVlFRblZBSFBvTUpaV25nVTE4Q29idm5vVDlE 
MFJPRHgAVXNxdjO2czBA4NE5OoRTJBOLIJRKzFEmdGFWTGpISmhPL2RqaWZVNDOiLCJhbXIiOlsicHdkIiwib 
WZhIlOsImFwcGlkIjoiNDIwMTMONzMtNGRjYi00NmI1LWI5MDYtZGVjN2M2YjOzM20xIiwiYXBwaWRhY3 
IiOilxliwiZmFtaWx5X25hbWUiOiJLYXVmZzZmlhbm4iLCJnaXZlbl9uYW11IjoiOXJlbmQtSmFuliwiaXB 
hZGRyljoiNDYuNDQuMTCyLjMA4IiwibmFtZSIG6IkFKSyB8IENyb251cyBDb21wYW55Iiwib21kIjoiMzM1 
NzNizWQtNjhmYiOOZTI3LWE3YjEtNWUzZmIzM2EO0N211IiwicHVpZCI6IjEwMDMwMDAwOEMIOEQZzRTIiL 
CJyaCI6IjAuQVlJQVpXZ229JNHRNWkVTTEFhSUIKTHRZSkQzdmJabHNzMU5CaGdlbV9Ud0J1SilDQUpFLi 
IsInNjcCI6InVzZXJfaWlwZXJzb25hdGlvbilsInN1Yil6Ik9DTWFmczkzTm9sVWMwZHVvWkgza31XZGU 
50UgwMGpNdW930ThlT2dmS2siLCJO0aWQiOiIlyMzIA4Njg2NS00YzhiLTQONjQtOGIwMSl1hMjBjNzRiYjUA 
MjOiLCJlbmlxdWVfbmFtZSI6ImFqa0Bjcm9udXMuY29tcGFueSIsInVwbil6ImFqa0Bjcm9udXMuY29tc 
GFueSIsInV0aSIG6Ikx3RU1QSlkyUTBXVHFnXOcyazBOQUEiLCJ2Z2XIiOiIxLjAiLCJ3aWRzIljpbIjYyZT 
kwMzkOLTY5Z2jUtNDIzNyO5MTkwLTAxMjE3NzEONWUxMCISImI3OWZiZjRkLTN1ZjktNDY4OS04MTOzLTC 
2YjE5NGUANTUwOSJdfO.ENWOhE9gplkerzbtK rmJp HPNYYLq2-TdyeE8F5LeGBtSpx3cgmoEe- 
p2BMpkIvrV8Fu9MZFpfDkBiSkKAWmSiyqiFdzK- 

RboLHD4cK3rclnalNMO0jgD hBmC2zgvv35fw3mUtGkMTfOzO0Gc9w- 
XHcnlMwgV7wGrxRUbAmCWLJ8s7qHYyg BRqpxW7xS- 
TILGOv1GCe6bBWZOrCiOgFlCAxLIpqlAIOQBs8hKiETBipyCm74r60BCJWAWn5DL2DzlfPPL- 
RUQi7pXTB2 QOIRMmKhC5AKDw7Y81K9OtPfiQEOl4Per5xuCi eXVrigtOxTXs8thHryb7niluTdXCYlg" 


} 


For using the access token, see the paragraph Using the access token. 


CLIENT CREDENTIALS FLOW 


The Client Credentials Flow, also referred to as service-to-service authentication, isa a 
non-interactive flow type and should be used by background applications. Web applications 
can also use this flow, especially when the user is not a user in Business Central. But be careful 
to still comply with the licensing terms. Desktop applications should avoid this flow because it 
requires the usage of a client secret, and desktop applications are not considered safe enough. 
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The app registration in the Entra portal should be configured as described in scenario 3 
background application. The app must also be registered in Business Central. See the 


paragraph Registering the app in Business Central for more information. 


The Client Credentials Flow basically consists of one step: a call to the token endpoint. 


The base URL can be copied from the app registration in the Entra portal. 


Open the Overview page of the app registration. Then click on Endpoints in the menu 


at the top of the page. Copy the OAuth 2.0 token endpoint (v2) from the popup. 


Home » Contoso > App registration 


ui My Business Centr 


| & Search 


I Overview 
&> Quickstart 
# Integration assistant 


X% Diagnose and solve problems 


Manage 
Branding & properties 
Authentication 
Certificates & secrets 
Token configuration 
API permissions 
Expose an API 

HÀ App roles 


Owners 


Endpoints 


OAuth 2.0 authorization endpoint (v2) 


https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize 


OAuth 2.0 token endpoint (v2) 


| https://login.microsoftonline.com/organizations/oauth2/v2.0/token 


OAuth 2.0 authorization endpoint (v1) 


https://login.microsoftonline.com/organizations/oauth2/authorize 


OAuth 2.0 token endpoint (v1) 


https://login.microsoftonline.com/organizations/oauth2/token 


OpenID Connect metadata document 


https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration 


Microsoft Graph API endpoint 


https://graph.microsoft.com 


Federation metadata document 


https;//login.microsoftonline.com/d6738d9b-6610-4ec3-b113-fd740095fa95/federationmetadata/2007-06/federationmetadata.xml 


WS-Federation sign-on endpoint 


https;//login.microsoftonline.com/d6738d9b-6610-4ec3-b113-fd740095fa95/wsfed 


Roles and administrators 


Manifest 


SAML-P sign-out endpoint 
| https;//login.microsoftonline.com/d6738d9b-6610-4ec3-b113-fd740095f295/saml2 


Support * Troubleshooting 


& New support request 


Depending on the app registration configuration, the URL must be modified before using 
it. In case the app registration is configured as a single-tenant application, then the URL will 
contain the id of the current Entra ID Tenant. The URL can then be used without further 
modification. 


If the app registration is configured as a multi-tenant application, the URL will contain the 
word organizations. This word must be changed into the id of the Entra ID that the 
application wants to access. Instead of the id, it is also possible to use the primary domain of 
the Entra ID Tenant. 


The request is of type POST. All parameters are passed in the body, which must be of type 


x-www-form-urlencoded. 


Description 

Indicates that we are using the Client Credentials 
flow. 

Copy the value from the overview page in the app 
registration. 


grant type client credentials 


client id 


Assigned in the app 
registration 
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scope The required permissions Always use static permissions: 
https://api.businesscentral.dynamics.com/.default 


client_secret Assigned in the Entra Always required. 
portal 


Here is an example of the request to retrieve the access token for a background 
application using the client credentials flow: 


POST https://login.microsoftonline.com/23286865-4c8b-4464-8b01- 
a20c74bb5824/oauth2/v2.0/token 

Content-Type: application/x-www-form-urlencoded 
grant_type=client credentials 

&client id=42013473-4dcb-46b5-b906-dec7c6b433d1 

&scope- https://api.businesscentral.dynamics.com/.default 

&client secret-Gq-8Q0-VlO .aU2mNhizqRX2zFLlAhRB-G3Q-gcvQ 


Notice that the request is to the same token endpoint as used in the Authorization Code 
Grant flow. But the parameter grant type is different, and the code is missing. 


The response for this web request will be a JSON-formatted response that contains the 
access token. It looks like the following: 


{ 


Meo eyes Bere 
Jewqeubrsews aug "8 09997 
VERE Spires sing 35997 


VaCESSS Token 
"eyJOeXAiOiJKV1QiLCJhbGciOiJSUzIl1NiIsIng1dCI6IilLSTNROW5OUjdiUm9meG1lWm9YcWJIWkdl 
dyIsImtpZCI6IilLSTNROW5OUjdiUm9meGllWm9YcWJIWkdldyJ9.eyJhdWOQiOiJodHRwczovL2FwaS5i 
dXNpbmVzc2NlbnRyYWwuZzHluYWl1pY3MuY29tliwiaXNzIjoiaHROCcHM6Ly9zdHMud21uZG93cy5uZXQvM 
jMyODYA4NjUtNGMAYi00NDYOLThiMDEtYTIwYzcOYmI1ODIOLyIsImlhdCI6MTY3NDMzNzMyMywibmml;j 
oxNjcOMzM3MzIzLCJleHAiOjE2NzOzNDEyMjMsImFpbyI6IkUyWmdZS2krblpwNzZkNEw3UXNGNmc5NUx 
hdzVBQTO09IiwiYXBwaWQiOilOMjAxMzQ3My00ZGNiLTQ2YjUtYjkwNilkZWM3YzZiNDMzZDEiLCJhcHBp 
ZGFjcil61jEiLCJpZHAiOiJodHRwczovL3NO0cy53aW5kb3dzLm51dC8yMzI14Njg2NSO0YzhiLTQONjOtO 
GIwMS1hMjBjNzRiYjUAMjOvIiwiaWROeXAiOiJhcHAiLCJvaWQiOiJiZ2jl110GU3NylkMTO2LTOzYTctYj 
dmMS03MmNl1ZDk3YTc3OTIiLCJyaCI61jAuQVlJQVpXZ229JNHRNWkVTTEFhSUIKkTHRZSkQzdmJabHNzMUS5 
CaGdlbV9UdO0J1SilDQUFBLiIsInJvbGVzIjpbIkFQSS5SZWFkV3JpdGUuOWxsIlOsInN1Yil6ImJmOWUA 
ZTc3LWQxNDYtNDNhNyliN2YxLTcyY2VkOTdhNzc5MilsInRpZCI6IjIzMjg2ODYlLTRjOGItNDQ2NCOAY 
jAxLWEyMGMGNGJiNTgyNCIsInVOaSI6ILlFTVFFOVnO3ROV1lek1XTOkxSm9BQUEiLCJ2Z2XIiOiIxLjAifOQ 
.WUk7L80NrJlqOYshA3yIF9kXICM7KyCeDPOMEX6ZTFwONOOHLEfFKD2Tc6jbupLzD9QNk2POnbbD9SIB 
ChyDEkPEO5K1qhd76RnkSZrydkieG2uhnxSAQPZ780JA4qNt0OAWJaV3iPUE7ER3Ha7QZGe439kfeCsQYv 
w1U 7W9fZkICSN7qUS5TFCdPcaywSG5tigDeDUEDj- 
JEj391n2BNYarC9hoHlzkILptcOwzJEOQSFCOZ5qLwzOzlnZbxzUIADiOzuwiEYVGnuCLcaBej 70s2Z2WyG 
uzGfuo0Po8alyiS7KHGPburgiV AEKFhC94nl6VtjfeHrOgRimTs b1SZQ" 

} 


USING THE ACCESS TOKEN 


In the previous paragraphs, we have seen how to retrieve a JSON response that contains 
the access token. To use the access, read the value from the JSON and add it to the 
Authorization header of a request as follows (the token has been shortened): 


Authorization: Bearer eyJOÜeXAiOiJKV1QiLCJhbGciOiJSUzIl.. 
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Business Central will automatically detect the user and the assigned permissions. Because 
the access token includes the Entra ID identifier, adding the tenant to the URL is not required. 
Instead of using this: 


https://api.businesscentral.com/cronus.company/v2.0/production/api/v2.0 


The URL can be changed into the following: 


https://api.businesscentral.com/v2.0/production/api/v2.0 


In the first URL above, the Entra ID Tenant or tenant id is cronus.company. This could also 
be replaced with the GUID identifier of the Entra ID Tenant. However, the same information is 
available in the access token and therefore the tenant id can be completely removed from the 
URL, making the URL independent and reusable for any tenant. 


You can also inspect the access token yourself by copying and pasting the value into one 
of these websites: 


e  https:;//jwt.ms/ 
e https:;//jwt.io/ 


The access token is valid for a short period. After about 60 minutes, the access token will 
expire and needs to be refreshed. This period of 60 minutes is the default, but depending on 
configuration settings, a random value is assigned between 60-90 minutes (75 minutes on 
average). The token response contains a value expires in with the duration in seconds from 
the moment that the request was made. 


REFRESHING THE ACCESS TOKEN 


After the access token has expired, a new access token needs to be retrieved. There are 
various ways to do so. It is obvious that the whole OAuth flow can be repeated, including 
logging the user if required. Because the user may be recognized as already logged in, the user 
will not see a login prompt. Moreover, because the user gave permissions before, the login 
procedure will skip that step and immediately forward to the redirect URL, which results in a 
popup that opens and closes automatically almost instantly. Alternatively, it looks like the 
browser is refreshing. This is not a good user experience, of course. 


A better way to retrieve a new access token is by requesting and using a refresh token. 
This can be achieved by adding extra scopes to the original request. The value of this scope is 
offline access. Multiple scopes are divided by a space, which should be escaped as $20 
in a URL. The authorization code request, including a refresh token, looks like the following: 


https://login.microsoftonline.com/23286865-4c8b-4464-8b01-a20c74bb5824/0auth2/v2.0/authorize 
?client id=42013473-4dcb-46b5-b90 6-dec7c6b433d1 


&response type-cod 

&response mode-query 

&redirect uri-https://www.mywebapplication.com/oauthlanding.htm 
&scope-https://api.businesscentral.dynamics.com/user impersonation%200ffline acce 
ss 
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The rest of the procedure is the same as before. Nevertheless, the response at the end 
will not only contain an access token but also contains the refresh token (values have been 
truncated): 


{ 
Meoidsil tyeta Bede 
"scope": "https://api.businesscentral.dynamics.com/user impersonation", 
yexpuiresgetmiu: m9 
Wee Gago alms disi 
VCCI TOKEM, 
"eyJOeXAiOiJKV1QiLCJhbGciOiJSUzIlNiIsIng1dCI6IilLSTNROW5OUjdiUm9meG1lWm9YcWJIWkdl 
dylIsImtpZCI6IilLSTNROW5OUjdiUm9meGllWm9YcWJIWkdldygJ9..", 
Wrotresheiokene 
"Q.AYIAZWgoIA4tMZESLAaIMdLtYJHMOAULLTbVGuQbex8a0M9GCAJE.AgABAAEAAAD-- 
DLA3VO7QrddgJg7WevrAgDs wUA9PO9FNkgbjVXwRHjqgZzPEc517SB7MpnJk- 
reKbq1U2sq BU2FuToy9ZgCfXjEeb-E99cDxMAeVIVR683pX1- 
mFiFNgCO4LwawBzWOzLxVhZ6qyEHJxGP8LVFhn0Ox.." 
} 


The refresh token is valid for 90 days, and can be used to retrieve a new access token 
within that period without user interaction. The request to the token endpoint must be changed 
as follows: 


POST https://login.microsoftonline.com/23286865-4c8b-4464-8b01- 
a20c74bb5824/oauth2/v2.0/token 

Content-Type: application/x-www-form-urlencoded 

grant_type=refresh token 

&client id=42013473-4dcb-46b5-b90 6-dec7c6b433d1 

&refresh token=0.AYIAZWgoI4tMZESLAaIMdLtYJHMOAULLT... 

&scope= https://api.businesscentral.dynamics.com/user impersonation 
&client secret-Gq-80-VlO .aU2mNhizqRX2zFLlAhRB-G3Q-gcvQ 


Please note that the request is to the same token endpoint, but the parameter 
grant type has a different value. Furthermore, instead of providing the code parameter, the 
parameter refresh token is provided. It also does not contain the redirect URL. 


The response will contain a new access token and a new refresh token that is again valid 
for the next 90 days. The previous refresh token is still valid90 days after it was acquired, but 
the new refresh token will have a longer lifetime. It is recommended to replace the previous 
refresh token with the new one. 


This procedure with a refresh token is only for user interactive flows like the Authorization 
Code Grant flow. Its purpose is to acquire a new access token silently. The non-interactive flow 
type Client Credentials flow can simply call the token endpoint again to get a new access token 
after the previous one has expired. 


Be careful with refresh tokens because they are quite powerful. Preferably, they should 
not be stored in a database to imitate a background process. Instead, delete the access token 
and the refresh token after the user closes the application and get new ones when the user 
starts the application. 
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Chapter 88: Sales & Purchase Documents 


An important core concept to understanding the Sales and Purchase Document API 
endpoints is that Business Central has different lifecycles for a document from many other 
platforms. Some examples include: 


e A Sales Quote can become one or more Sales Orders. 

e Sales Orders may be shipped and invoiced multiple times in different steps, becoming 
Posted Sales Shipments and Posted Sales Invoices. 

e Sales Invoices can be posted multiple times, becoming multiple Posted Sales Invoices. 

e When the Sales Quotes, Sales Orders, and Sales Invoices are fully posted, they are often 
deleted entirely (depending on configuration). 


This makes it very difficult to integrate Business Central with other platforms with a longer 
lifecycle workflow. 


This resulted in the API Architecture exposing Sales & Purchase Documents trying to 
present information in a different lifecycle than Business Central natively supports. 


To accomplish this, the API does not present documents directly from the Business Central 
entities. Instead, it relies heavily on dynamically generating “aggregate” layers, where 
information about the documents is created and maintained. 


Below are some examples of how the Sales Order and Sales Invoice documents work — 
this pattern of how the flow applies similarly to the Purchase Order and Purchase Invoice 
documents. 


API SALESORDERS 


The API page for Sales Orders is based on the "Sales Order Entity Buffer" table. This table 
holds a copy of all records in the "Sales Header" table of type Order. This is managed from 
codeunit "Graph Mgt - Sales Order Buffer". 


Similarly, the API page for Sales Order Lines is based on the "Sales Invoice Line Aggregate" 
table. The word /nvoice in this name is not a typo; this is really the name. The same table is also 
used for the Sales Invoice Line API. However, unlike the "Sales Order Buffer" table, the lines are 
not copied over. Instead, the API pages use them as temporary source tables and fill them on 
demand. See below for a full list of all buffer tables used by the sales and purchase document 
APIs. 


Here is a high-level dataflow diagram for the salesOrders API: 
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salesOrders 
API 


Propagate 

Insert 

update 

Propagate Delete 
Insert 
update 
Delete 
from API 


g Synchronize 
Codeunit Insert 
Sales Header Graph Mgt Update 

Sales Order Delete 
Buffer from table events 


Sales Order Entity Buffer 


Table events 
Insert 
Update 
Delete 


As you can see, the salesOrders API reads data from the table “Sales Order Entity Buffer”. 
It does not insert or update data in that table. At least not directly. The API page is based on 
that table, so when you insert a new order or update an existing one, the API page uses the 
same table to store the values. However, right before it inserts or updates it in the database, it 
calls the codeunit “Graph Mgt - Sales Order Buffer" to propagate the values to the real "Sales 
Header" table. This happens in the OnInsert / OnModify / OnDelete triggers in the API page. 


For a deeper dive into the code behind this aggregate flow and customizing the 
endpoints (which is a development topic beyond the scope of this book), see: 


https://www.kauffmann.nl/2021/04/16/extending-standard-apis-2 


Note: This same flow is used for other Sales documents, such as 
Sales Quotes. 


API SALESINVOICES 


One the other hand, API page for Sales Invoices is based on the table “Sales Invoice Entity 
Aggregate”. From the API point of view, the data flow is the same as with sales orders. However, 
there is a difference from a functional perspective. 


The table “Sales Invoice Entity Aggregate” does not only contain unposted sales invoices 
from table “Sales Header”, but it also contains posted invoices from table “Sales Invoice 
Header”. The idea is to have one endpoint that returns unposted and posted sales invoices. On 
top of that, the posted sales invoice will keep the same id. As a result, the sales invoice will 
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keep the same resource URL throughout the entire lifecycle from unposted to posted 
document. 


Here is the high-level data flow diagram for the salesInvoices API: 


salesInvoices 
APL 


Propagate 
Insert 
Update 
Delete 
Propagate 
Insert 
Update 
Delete 
from API 


Codeunit synch 
Sales Header Sales Invoice yncapom ces Sales Invoice Entity Aggregate 
Sales Invoice data 
Aggregator 


Post Table events 
invoice Insert 
Update 
Delete 


Codeunit 


Sales-Post OnBeforesalesInvHeaderInsert 


Inserts afsaies Invoice Header 


STATUS FIELD 


One thing about the salesOrders and salesInvoices APIs that can be confusing is the status 
field. We all know the status field in the table "Sales Header". Nevertheless, the value Open in 
the sales APIs has a different meaning than the same value on the sales document in the 
Business Central Ul. 


In the API, it means that the sales document is Released. In other words, the status Open 
in the API means that the sales document is not open in terms of Business Central UI. 


Instead, the status Draft in the APIs is equivalent to Open in the sales document. This 
reflects the theory that the Business Central team tried to align the APIs with common status 
values used by other solutions. 


SALES DOCUMENT STATUS 


The status of sales orders and invoices is based on the enum "Sales Document Status," 
whose values are as explained in the following table: 


Description 
The sales document can be modified. 


Released The sales document is ready to be shipped and cannot be 
modified. 
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Pending Approval The sales document is waiting to be approved before being 
released. 


Pending prepayment The sales document waits for an upfront payment from the 
customer before being released. 


SALESORDER API STATUS 


The status field of the salesOrder API is based on the Enum "Sales Order Entity Buffer 
Status," whose values are as explained in the following table: 


Value Description 


Draft The sales order status is Open. 
In Review The sales order status is Pending Approval. 
Open The sales order status is Released or Pending Prepayment. 


SALESINVOICES API STATUS 


The status field of the salesInvoices API is based on the Enum “Sales Order Entity 
Aggregate Status," whose values are as explained in the following table: 


Description 
Unknown use. 
Unposted sales invoices with status Open. 

In Review Unposted sales invoice with status Pending Approval. 

Open If unposted: status Released or Pending Prepayment. 
If posted: waiting for payment. 

Paid Posted invoice is closed. 

Canceled Posted invoice is canceled, and a corrective credit memo has been 
created for the posted invoice. 

Corrective Posted invoice is canceled, and a new sales invoice has been 
created. 


Note: These Status fields not aligning with the native BC Status 
field can be a huge source of confusion! Talk about status 
with extreme care. 


API SALESLINES 


While the sales header values are duplicated in the buffer tables, the sales lines are not. 
Instead, all APIs for sales lines use the same table: "Sale Invoice Line Aggregate," as a temporary 
source table. The lines are loaded into the temporary table by calling the function LoadLines 
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in codeunit “Sales Invoice Aggregator” (essentially a TransferFields followed by extra calls to 
update the line amounts). 


Inserting and updating sales lines is done similarly to the sales headers. The codeunit 
“Sales Invoice Aggregator” has functions to propagate the field values from the temporary 
record to the table “Sales Line.” The function TransferFieldsWithValidate from codeunit “Type 
Helper” is used. 


AGGREGATE TABLE MAPPING 


This table outlines the various aggregate tables used by the various API Endpoints for the 
Sales and Purchase Documents. 


salesQuotes Sales Quote Entity Buffer 
salesQuoteLines Sales Invoice Line Aggregate 
salesOrders Sales Order Entity Buffer 
salesOrderLines Sales Invoice Line Aggregate 
salesInvoices Sales Invoice Entity Aggregate 
salesInvoiceLines Sales Invoice Line Aggregate 
salesCreditMemos Sales Cr. Memo Entity Buffer 
salesCreditMemoLines Sales Invoice Line Aggregate 
purchaselnvoices Purch. Inv. Entity Aggregate 
purchaselnvoicelines Purch. Inv. Line Aggregate 
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Chapter 89: Performance 


There are some considerations and design strategies to get the best performance out of 
working with the Business Central API. Not only does this make your calls run faster, but it 
reduces the impact on the whole system, making all operations smoother while resolving API 
requests. 


For the latest and complete listing of all Microsoft recommended performance 


improvements, review the Microsoft Learn page: https://learn.microsoft.com/en- 
us/dynamics365/business-central/dev-itpro/webservices/odata-client-performance. 


Many of these tips are sourced from that page and included in this book for easy 
reference and completeness. Some of these tips are either SaaS (cloud) specific or require 
specialized knowledge and setup if working with On-Premises editions. 


Read-Only Intent 


If the header Data-Access-Intent: ReadOnly is added to a GET request, Business 
Central can optionally serve the response from a replica of the dataset, which can result in large 
performance gains. 


See this page for more information: 


https://learn.microsoft.com/en-us/dynamics365/business-central/dev- 
itpro/developer/devenv-connect-apps-tips#DataAccessIntent 


Batch Requests 
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When submitting data to the API, consider using the $batch functionality, which makes 
all of the information submitted part of a single batch if you also enable the Isolation: 
snapshot header, which can significantly improve the performance of written transactions. 


See this page for more information: 


https://learn.microsoft.com/en-us/dynamics365/business-central/dev- 


itpro/webservices/use-odata-batch 


Use Filters, Select and Top 


Whenever possible, limit the response the API has to generate. Using $filters and 
$top can significantly reduce the number of records included, and using $select can reduce 
the number of fields per record. These are essential tools, particularly if using expensive 
$expand calls. These are covered in Part 1: Chapter 2: Reading / GET (page 17). 


Additionally, if you are fetching data that may comprise an extensive history of data, 
Business Central makes available the LastModifiedoOn field as a system generated value on 
all records, to save an enormous amount of data from being fetched. 


Paging Considerations 


Many times, when building against APIs, client-side paging using $top and $skip 
options are is frequently used. With the heavily optimized Business Central engine, you can 
instead ask the server to handle the paging for you, and it will be much better. 


This is handled by adding an HTTP Header, Prefer: odata.maxpagesize-X, which 
instructs Business Central to page the record set. A new OData entry will appear to at the end 
of the data results with a new URI that includes a $skipToken value. You can use that call, 
combined with the same Prefer header, to get the next set of entries. 


For more information, including how to enable this functionality for the on-premises, see 
the Learn page: 


https://learn.microsoft.com/en-us/dynamics365/business-central/dev- 


itpro/webservices/server-driven-paging-in-odata-web-services 


Accept-Language 


While not strictly a performance tip, this is also a good HTTP Header to know about. When 
accessing the Business Central API, the system and other environment settings may influence 
the captions and formatting of fields and data. To ensure calls get consistent results regardless 
of system settings, API calls can include an HTTP Header Accept-Language to force a particular 
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language and regional settings. This also influences how error messages are displayed. As such, 
you may need to set a specific language to display the correct error language for users. 


For more information, refer to: 


https://learn.microsoft.com/en-us/dynamics365/business-central/dev- 
itpro/developer/devenv-connect-apps-tips#AcceptLanguage 


Handling Limit Errors 


When building against the Business Central API, it is also a good idea to plan for when 
you hit API limits, such as too many requests or timeouts. 


The two primary response HTTP Status codes you should prepare for are: 


e 429 - too many requests. Here you will want to have a mechanism for pausing 


API calls and retrying later. 
e 504 - gateway timeout. Here, the API is taking too long to respond. This is often 
an issue with trying to return too much data or build too complex of a data set. 


For more information, see: 


https://learn.microsoft.com/en-us/dynamics365/business-central/dev- 
itpro/performance/performance-developer#how-to-handle-large-volumes-of-web-service- 


calls 
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Chapter 90: Filtering Syntax 


Because the Business Central API complies with the OData rules, filtering is handled in 
compliance with OData methods. 


For the latest and complete listing of all supported Filtering, make sure to review the 


Microsoft Learn page: https://learn.microsoft.com/en-us/dynamics365/business-central/dev- 
itpro/webservices/use-filter-expressions-in-odata-uris 


The below table is sourced from that page and included in this book for easy reference 
and completeness. 


Equivalent AL 


Definition Example and explanation expression 


$filter-Entry No gt 610 and Entry No lt 615 


Query on GLEntry service. Returns entry numbers 611 
through 614. 


$filter-Country Region Code eq 'ES' and Payment Terms Code 
eq '14 DAYS' 


Query on Customer service. Returns customers in Spain 
where Payment Terms Code-14 DAYS. 


$filter- Country Region Code eq 'ES' or Country Region Code 
eq 'US' 


Query on Customer service. Returns customers in Spain 
and the United States. 


Alert: You can use OR operators to apply different 
filters on the same field. However, you cannot use OR 
operators to apply filters on two different fields. 


Less than 


$filter-Entry No lt 610 


Query on GLEntry service. Returns entry numbers that 
are less than 610. 
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Definition 


Equivalent AL 
Example and explanation expression 
$filter= Entry_No gt 610 


Query on GLEntry service. Returns entry numbers 611 
and higher. 


Greater 
than or 
equal to 


$filter=Entry_No ge 610 


Query on GLEntry service. Returns entry numbers 610 
and higher. 


Less than 
or equal to 


$filter=Entry_No le 610 


Query on GLEntry service. Returns entry numbers up to 
and including 610. 


Different 
from (not 
equal) 


$filter=VAT_Bus_Posting Group ne 'EXPORT' 


Query on Customer service. Returns all customers with 
VAT_Bus_Posting_Group not equal to EXPORT. 


endswith 


$filter-endswith(VAT Bus Posting Group, 'RT') 


Query on Customer service. Returns all customers with 
VAT Bus Posting, Group values that end in 'RT’. 


startswith 


$filter-startswith(Name, 'S') 


Query on Customer service. Returns all customers 
names beginning with 'S'. 


contains 


$filter-contains(Name, 'urn') 


Query on Customer service. Returns customer records 
for customers with names containing the string "urn". 


$filter-indexof(Location Code, 'BLUE') eq @ 


Query on Customer service. Returns customer records 
for customers having a location code beginning with 
the string BLUE. 


$filter-replace(City, 'Miami', 'Tampa') eq 'CODERED' 


$filter-substring(Location Code, 5) eq 'RED' 


Query on Customer service. Returns true for customers 
with the string RED in their location code starting as 
position 5. 


$filter-tolower(Location Code) eq 'code red' 
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Equivalent AL 
Definition Example and explanation expression 


$filter-toupper(FText) eq '2ND ROW' 


$filter-trim(FCode) eq 'CODE RED' 


$filter-concat(concat(FText, ', '), FCode) eq '2nd row, 
CODE RED' 


$filter-round(FDecimal) eq 1 


$filter-floor(FDecimal) eq @ 


$filter-ceiling(FDecimal) eq 
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Chapter 91: API Bugs 


While writing this book, an array of bugs or unexpected design behaviors surfaced. 
Delightfully, this chapter is fairly small, but for those of you working with various versions of 
the API, it can be valuable to note that you may run into these. 


Note that we did not regressively test every version for these bugs for which versions they 
were either introduced or resolved. Thus, hopefully you will not have great need of this chapter. 


JOURNALS 


This endpoint has defects in the expansion logic for the accounts endpoint. 


First, it forces a linkage to the G/L Account table, but in a Gen. Journal Batch, you can 
use a variety of balancing account types: 


General Journal Batches O +New  & Edit List 


— DEFAULT : Default Journal Batch 


MONTHLY Monthly Journal Entries 2910 GJNL-GEN 
Customer 
Vendor 
Bank Account 
Fixed Asset 
IC Partner 
Employee 


If you use anything other than a G/L Account type, this expansion will not work. 


Older Version note: Additionally, in versions prior to v20, they did not link the Bal. 
Account No. by the Id correctly, which results in errors no matter what value is provided, which 
will look like this: 


"error": f 
eode Map eaten e Boc ono Biscoepi ong 
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"message": "The filter \"''\" is not valid for the System ID field on the 
G/L Account table. Invalid format of GUID string. The correct format of the GUID 
string is: CDEF7890-ABCD-0123-1234-567890ABCDEF where 0-9, A- 
E symbolizes hexadecimal digits. CorrelationId:  d2946940-b5c1-476f-bb60- 
95fbbd1731fe." 
} 


} 


JOURNAL LINES 


This endpoint has two major filters built right into it, as follows: 


trigger OnOpenPage () 
begin 
Rec.SetRange ("Document Type", Rec."Document Type"::" "); 
Rec.SetRange ("Account Type", 
Rec."Account Type"::"G/L Account", Rec."Account Type"::"Bank Account") ; 
end; 


Document Type blank is the only line type allowed in this Endpoint. 


The Account Type (and Balancing Account Type) must also be either a G/L Account or 
a Bank Account. 


It is our opinion that restricting the Journal API to allow only a subset of the many different 
combinations of valid entries is a defect, and a shortcut that is taken but should be corrected. 


COUNTRY/REGION 


In earlier versions of BC, several endpoints had countryRegion set as Navigation options. 
However, there are places where this is supposed to be connected by the systemld, and it is 
not. This results in the following error message when using $expand=countryRegion: 


Mearcogr se f 
Werxole Ug  aejodbaxermeahorat Wal Ieeclinaieonelip(etsyoycsloun m 
"message": "The filter \"US\" is not valid for the System ID field on the 


Country/Region table. Invalid format of GUID string. The correct format of the G 
UID string is: CDEF7890-ABCD-0123-1234-567890ABCDEF where 0-9, A- 
F symbolizes hexadecimal digits.  CorrelationId:  elbbce0a-1999-4cd3-87bd- 
est SSrel 9 Sessa 4 

} 


} 
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DEFAULT DIMENSION 


While you can specify Default Dimensions on a wide array of tables throughout the 
system, even some built in tables that support Dimension are not available to the API. 


This is because the Parent Type field enum that is exposed as the endpoint only has a 
small subset of the possible values: 


e Customer. 
e |tem. 

e Vendor. 

e Employee. 


This results in any Default Dimensions outside of this list displaying to display via the API 
in a strange way, such as this result for a Default Dimension on a Salesperson: 


{ 

"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/{{tenantID}} 
/APIBook/api/v2.0/Smetadata#companies ({ {companyID}})/defaultDimensions/Sentity", 

"@odata.etag": "W/N"JzIWOzEwNTUzNjglNjcxOTgwNzgxNzIxMTswMDsnN"", 

"id": "d490f4e6-ee9e-ed11-9a8a-6045bd02a733", 

Moguccimeiyjees Y M 

"parentId": "00000000-0000-0000-0000-000000000000", 

"dimensionId": "6e572523-df3a-edll-bbae-6045bd8e554a", 


"dimensionCode": "SALESPERSON", 

"dimensionValueId": "d25a2523-df3a-edll-bbae-6045bd8e554a", 
"dimensionValueCode": "JO", 

Moo ssim e Vicleidai ont: e Same) Coe 


You will note that the parentld field is a blank GUID. 


This also means you cannot filter on Default Dimensions outside of this short list. For 
example, filtering on parentType eq ‘Salesperson’ will result in the error: 


Petro 
"code": "Application InvalidOptionEnumValue", 
"message": "'Salesperson' is not an option. The existing options are: x0 


020 ,Customer,Item,Vendor,Employee  CorrelationId:  cb8b45ba-b5b4-44a1-974d- 
77db31a0c2a3." 
} 


} 


If you filter on a parentId that is a Salesperson, you will instead get a blank result, as 
that parentld is of a type unknown to the API. 
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APPLY VENDOR ENTRIES 


Note for older versions (mostly versions older than BC18), the Apply Vendor Entries 
functionality, upon validation of the Applied-To ID field, this removes the critically needed 
Applies-to Document Type field on the Payment Journal Line. This means that Payment 
Journal Line becomes completely unavailable to the API, including the Apply Vendor Entries 
endpoint. 


Unfortunately, using this endpoint immediately renders the record unavailable for further 
use of this endpoint. 


SALES SHIPMENT 


Unlike all the other Sales Documents, this endpoint (as of BC 24.0) uses a field called 
billToCustomerID referencing a BC user editable value, not a GUID. For example, on the Sales 
Credit Memo, there's a pair of fields like so: 


"pillToCustomerId": "6d15971e-df3a-ed11-bbae-6045bd8e554a", 
"pillToCustomerNumber": "20000", 


But on the Sales Shipment, you'll find: 


"billToName": "Trey Research", 
TpiiiToCus tomer TDIR 120000) 


This is inconsistent and against the way it should be, so it is noted here as a bug. 
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PART 9: ADDITIONAL RESOURCES 


This Part shares some additional resources that may assist working with the Business 
Central API. 
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Chapter 92: API Training 


This chapter is admittedly more aspirational than informative. 


If you know of additional resources, please share them with us so we can add them. 


MICROSOFT LEARN 
There is, of course, the free Microsoft Learn course: 


https://learn.microsoft.com/en-us/training/modules/work-with-api/ 


KAUFFMANN COURSES 


Arend-Jan Kauffmann also offers paid courses in use of and development of the API, along 
with a wide array of deeply informative free blog posts on the subject. Find out more at: 


https://www.kauffmann.nl/bc-apis-online-course/ 
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Chapter 93: Telemetry 


Particularly when working with Business Central SaaS (cloud), but even for on-premises, 
if enabled, Telemetry data can be a critical tool for providing insight into the use and 
performance information about API calls. 


For example, if an ISV or custom solution adds an API to an environment, how do you 
evaluate if it is too complex or impacting performance? 


While teaching about enabling and use of Telemetry is beyond the scope of this book, 
understanding that this is an option and its value is important for good systems management 
and use. 


Firstly, to read all about Telemetry data and the current information about what is 
collected, the best source of information is the Learn page: 


https://learn.microsoft.com/en-us/dynamics365/business-central/dev- 


itpro/administration/telemetry-webservices-trace 


Here are some examples of a Power BI dashboard looking through performance 
measurements, to give a sense of some of the great data available. 
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Integrations 


Integrations Tenant/Environment/Company 
All 


This page shows web service integrations to and from external systems (excluding the use of Microsoft connectors) 


Web Service Integrations by Publisher / App Integrations 


Publisher / App Incoming Outgoing Total App 
X 


@ (Blank) 
928 928 


15 149 164 @3PL Manager 
100 100 @4Ps API W1 


5 Microsoft 

3 Theta Systems Limited 

- 

= APS B.V. 

= NaviPartner 

= Hougaard 

3 Cosmo Consult 
Total 


24 18 42 
28 28 
16 16 Calls over the Day - (UTC-06:00) Central Time (US & 


12 7 Canada) 
402 


] 
= Abakion 7) 79 


Direction 
@ Incoming 


@ Outgoing 


: : : Calls over the Week 
Web Service Integrations by Endpoint Direction 


Count Direction Endpoint @incoming 500 
X 


900 Incoming MS/ODataV4/Company @Outgoing 

96 Outgoing https://api.stripe.com/v1/plans 

78 Outgoing https://e2e-teststore.myshopify.com/admin/api/2022-01/graphql.json Lj BH 

25 Outgoing https;//abscbappO1.azurewebsites.net/api/AzureTableStorageCreate 0 = 
Mon Tue 


Wed Thu Fri Sat Sun 


18 Outgoing https://api.navipartner.dk/ServiceTierUser 


The Integrations PowerBl dashboard shows information about Web service calls flowing 
in and out of the system, giving a sense of the time and days of the calls. 


Incoming Web Services 


Incoming Web Service Errors Tenant/Environment/Company 
All 


Look at the distribution of failures calling web service endpoints (not using the Microsoft connectors). Any call with http status <> 200 is an error and is 
an indication of an integration to Business Central not working properly. 


Incoming Web Service Errors by Environment All Last 7 days Since Yesterday 


Count Domain AAD Tenant Id Environment 
Name 


8 €07b78fa-9b87-48b1-a1c6-b75ba2d4dfe4 Test 1 5 0 0 


d88985a1-c863-442c-bb5f-dc622e480a8d — Production 


Incoming WS Call Errors Incoming WS Call Errors Incoming WS Call Errors 


Web Service Errors by Error Type 


Incoming Web Service Error by Error Types Error Type 


Count Error Type Http Code 
X @Sxx - Server error 


9 4xx- Client error 
5 4xx - Client error 


@4xx - Client error 


1 5xx- Server error 
15 


Web Service Errors by Catego 
Endpoints Hun dinis 


Http Category Endpoint @Api 

Status = 6 DataV4 

400 Api MS/api/4PS/App/v1.0/subscriptions 

404 Api MS/api/4PS/App/v2.0/subscriptions 

501 Api MS/api/4PS/job/v1.0/companies 

400 Api MS/api/4PS/Job/v1.0/companies()/jobs() 

404 Api MS/api/4PS/job/v2.0/subscriptions 

400 — ODataV4 MS/ODataV4/Finansposter. Excel/$count Web service errors over the Day - (UTC-06:00) Central Time (US & 


*——49—* 121% 
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The Incoming Web Service Errors report gives detailed information about the errors 
that have accrued, with detailed information about the timing, source, and nature of the errors. 


Login Errors Tenant/Environment/Company 


All 


Look at the distribution of failure reasons. Ideally, you should see no data here. Maybe some integrations use a wrong user or wrong company name? 


Login Errors by Environment All Last 7 days Since Yesterday 


Count Domain AAD Tenant Id Environment 


B 0 0 0 


Login Errors Login Errors Login Errors 


Login Failures by Authorization Step 


Client and User types that gets login errors 
Count Session Type Client Type User Type 


Login Failures by Session Type (UI, WS, or Background) 


Where does the error occur and why 


Count Authorization Step Failure Reason 


Login Failures by User type 


The Login Errors report gives extensive information about login errors for environments, 
which can be an essential tool to determine the cause of API login errors. 


Incoming Calls Performance 
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Incoming web service call performance Tenant/Environment/Company 
All 


Incoming web service calls can take up a lot of resources on an environment. 


Look for 
* both high number of calls and high avg. durations. 
+ category of calls: SOAP is slower than OData, which is slower than the API stack. 
+ http codes other than 200. These calls take up resources but do not succeed 


Incoming Webservice Call Statistics Incoming Webservice Calls by HTTP code 


Count Endpoint Category Sum time Avgtime a Http code 
(sec) (ms) e. 


X 
MS/ODataV4/Company ODataV4 1357 1503 
MS/api/4PS/ProgressApp/v1.0/subscriptions() Api 73 920 
MS/api/v2.0/companies Api 13236 
MS/api/4ps/hr/v1,0/subscriptions() Api 133 
MS/api/Contoso/Productivity/v2.0/subscriptions() Api 6234 
MS/api/v2.0/subscriptions() Api 5325 Incoming Webservice Calls by Category 
MS/api/microsoft/runtime/beta/companies Api 259 Category 
MS/api/4PS/job/v1.0/companies Api 24220 e^o 
MS/api/4PS/ProgressApp/v1.0/subscriptions Api 22 6 ODataV4 
MS/ODataV4/Finansposter. Excel ODataV4 4353 
MS/api/v2.0/contacts Api 3673 
MS/api/microsoft/runtime/beta/companies()/webhoo Api 14281 
kSupportedResources 
MS/api/4PS/App/v1.0/subscriptions Api 5671 

127 MS/api/microsoft/runtime/beta/apiRoutes Api 281 


1219 MAC LA tbe hel Dicubecrintionc Ani 21 24 v 
12567 3019 240 @ Edit in Excel 


p200 


X 


@soap 


Incoming Webservice Calls by Connector 


Connector 


Extension details (in which extension does the endpoint come from) Q Power app/automate setup 
Publisher / App / App Id / Version Count v 


The Incoming web service call performance details the performance of different 
endpoints, along with insights about the nature of the calls that drive those metrics. 


Telemetry is collected for Environments and Apps. 
To learn more about PowerBl against the Environment telemetry, see: 


aka.ms/bctelemetryreport 


To learn more about PowerBl against the App telemetry, see: 


aka.ms/bctelemetry-isv-app 


To find out more and to stay updated, it is strongly recommended that you follow the 
Business Central Telemetry Newsletter: 


https://www.linkedin.com/newsletters/6981923051273658368/ 
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Chapter 94: Custom API 


While providing step-by-step guides on how to customize or develop custom API 
solutions is beyond the scope of this book (it is already 500+ pages), there are a variety of 
resources we would encourage readers to jump off from. 


Custom API Development 


Creating APIs is done with AL Development efforts. There are development resources and 
training on this topic. Much as API training, Arend-Jan Kauffmann has been teaching courses 
on this topic for some time, so to learn more, view his course offerings here: 


https://www.kauffmann.nl/bc-apis-online-course/ 


He also has a wide array of blog posts about how to create these endpoints. 


Data Braider 


Spare Brained Ideas also has an AppSource solution for easy, no-code custom API 
creation: 


https://sparebrained.com/appsource/databraider/ 


Simple Object Designer 


Erik Hougaard has an AppSource solution that allows users to modify Business Central 
without writing code in a wide variety of ways. One of the many features allows creation of 
custom APIs: 


https://www.hougaard.com/designer/ 


API Query Generator 


Kennie from Microsoft has also released a toolset, called the API Query Generator, 
designed to help allow consultants to tailor a CSV file with the needed API information need 
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which can then be converted to AL. The desired outcome is that these CSV files can be 
translated as part of a pipeline, making it feasible for non-developers to assist with API 
development. 


Find out more at: 


https://github.com/microsoft/BCTech/tree/master/samples/APIQueryGenerator 
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Chapter 95: Topics Not Covered (Yet) 


While we've we have done our best to cover critical topics and many core items, there 
were a small array of topics that we know did not fit into this edition, and we may cover in 
future editions, either at all or in more detail: 


Financial Reports API 

Administration API. 

Automation API. 

Cloud Migration API. 

Larger explanation of Batch Requests. 
Unbound Actions. 

Webhooks. 

More depth on Deep Inserts. 


Since this book is specifically about the “API V2" extension, there are an array of additional 
fantastic endpoints that have been added to Business Central over many major releases that 
would create an entire additional book's worth of content. 
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PART 10: INDEX 


This section is a reproduction of Chapter 7: The API v2.0 List but copied here to easily 


locate and use. 


Endpoints Alphabetically 
accounts 


Business Central 
Page / Report 
Chart of Accounts 


accountingPeriods 


Accounting Periods 


agedAccountsPayables 


Report: Aged Accounts 
Payable 


agedAccountsReceivables 


Report: Aged Accounts 
Receivables 


applyVendorEntries 


Payment Journal -> 
Apply Entries 


attachments 


Incoming Documents 


balanceSheets 


Financial Reports 


bankAccounts 


Bank Accounts 


cashFlowStatements 


Financial Reports 


companies 


Companies 


companylInformation 


Company Information 


contacts 


Contacts 


contactsInformation 


Contact Card -> 
Business Relations 


countriesRegions 


Countries/Regions 


currencies 


Currencies 


currencyExchangeRate 


Currency Exchange Rate 


customers 


Customers 


customerContacts 


Contact 


customerFinancialDetails 


Customers 


customerPayments 


General Journal 


customerPaymentJournals 


General Journal Templates 
-> Batches 


customerReturnReasons 


Return Reasons 


customerSales 


«[&| «&I&IK«|&I&«|&[«|&| SIRIS IRIS IRIS IR «| «| IRIS 


Customer and Customer 
Ledger Entries 
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Endpoints Alphabetically 
defaultDimensions 


Business Central 
Page / Report 
Default Dimensions 


dimensions 


Dimensions 


dimensionSetLines 


Dimensions 


dimensionValues 


«[& « |« 


Dimension Values 


disputeStatus 


Dispute Status 


documentAttachments 


Document Attachments 


employees 


Employees 


fixedAssets 


Fixed Assets 


fixedAssetLocations 


FA Locations 


generalLedgerEntries 


G/L Entries 


generalLedgerSetup 


General Ledger Setup 


generalProductPostingGroups 


Gen. Prod. Posting Groups 


incomeStatements 


Financial Reports 


inventoryPostingGroups 


Inventory Posting Groups 


items 


Items 


itemCategories 


Item Categories 


itemLedgerEntries 


Item Ledger Entries 


itemVariants 


Item Card -» Variants 


journals 


General Journal Templates 
-» Batches 


journalLines 


General Journal 


locations 


Locations 


opportunities 


Opportunities 


paymentMethods 


Payment Methods 


paymentTerms 


SISIAISIS SIS 


KINI ISIS| SIS 


KISIAISIS| SIS 


Payment Terms 


pdfDocument 


Varies by Filters 


pictures 


Varies by Filters 


projects 


Jobs 


purchaseCreditMemos 


Y 
v 
M 
v 
v 
v 
v 
v 
M 
vV 
Y 
v 
M 
v 
Y 
M 
M 
v 
M 
M 
M 
M 
v 


SISS 


SISS 


Purchase Credit Memos or 
Posted Purchase Credit 
Memos 


purchaseCreditMemoLines 


Purchase Credit Memos or 
Posted Purchase Credit 
Memos 


purchaselnvoices 


Purchase Invoices or 
Posted Purchase Invoices 


purchaselnvoiceLines 


Purchase Invoices or 
Posted Purchase Invoices 


purchaseOrders 


Purchase Orders 


purchaseOrderLines 


Purchase Orders 


purchaseReceipts 


Posted Purchase Receipts 


purchaseReceiptLines 


Posted Purchase Receipts 


retainedEarningsStatements 


Financial Reports 
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Endpoints Alphabetically 
salesCreditMemos 


Business Central 
Page / Report 
Sales Credit Memos or 
Posted Sales Cred. Memos 


salesCreditMemoLines 


Sales Credit Memos or 
Posted Sales Cred. Memos 


salesInvoices 


Sales Invoices or 
Posted Sales Invoices 


salesInvoiceLines 


Sales Invoices or 
Posted Sales Invoices 


salesOrders 


Sales Orders 


salesOrdersLines 


Sales Orders 


salesQuotes 


Sales Quotes 


salesQuoteLines 


«l«««| «s «s «| «IE 


««««s| «s «s «s «Eu 


«[&«« «s «s «s «an: 


Sales Quotes 


salesShipments 


Posted Sales Shipments 


salesShipmentLines 


Posted Sales Shipments 


shipmentMethods 


Shipment Methods 


taxAreas 


VAT Bus. Posting Groups or 
Tax Areas 


taxGroups 


VAT Prod. Posting Groups or 
Tax Groups 


timeRegistrationEntries 


Time Sheets 


trialBalances 


Report: Trial Balance 


unitsOfMeasure 


Units of Measure 


vendors 


Vendors 


vendorPayments 


General Journal 


vendorPaymentJournals 


General Journal Templates 
-» Batches 


vendorPurchases 


«| «|&«|&««[«| «| ««l&«l&«««s| «s SSS 


Vendor and Vendor Ledger 
Entry 


* Unless otherwise noted above, the API v2 was added in 17.0, so the endpoints listed with no 


marking are valid as of 17.0 forward. 


PART 10: INDEX 


CHAPTER 95: ToPICS NOT COVERED (YET) 


